Implement save_pipeline_job MCP tool
What does this MR do and why?
Adds save_pipeline_job so MCP clients can play manual CI/CD jobs, optionally with environment or file variables.
Uses the existing jobPlay GraphQL mutation, checks job state and permissions, and returns job and pipeline details.
References
Closes: #597698
Related: gitlab-org#22783
Part of the October 2026 Community Co-Create Cohort: gitlab-org/developer-relations/contributor-success/contributors-gitlab-com#794
Screenshots or screen recordings
Demo
The recording demonstrates:
- Inspecting a manual job before playing it.
- Playing a job without variables.
- Playing another job with environment and file variables.
- Checking the returned job details and execution logs.
- Rejecting a completed job without creating a retry.
Claude code MCP tool registration
How to set up and validate locally
MCP tool registration
- Connect Claude Code with GDK MCP
- Trigger the command
/mcpin Claude Code CLI and then navigate toView toolsto check if thesave_pipeline_jobMCP tool is now registered or not.
MCP tool functioning with prompt
- On a test project, create a test pipeline:
Example used in above demo video
On a test branch, add this .gitlab-ci.yml. Adjust the image or runner tags if your runner requires them.
image: alpine:3
stages:
- test
mcp_plain:
stage: test
when: manual
allow_failure: true
script:
- echo "MCP_PLAIN_OK"
mcp_variables:
stage: test
when: manual
allow_failure: true
script:
- 'test "$E2E_DEFAULT" = "hello-from-mcp"'
- 'test "$E2E_EXPLICIT" = "explicit-value"'
- 'test -f "$E2E_CONFIG"'
- 'test "$(cat "$E2E_CONFIG")" = "mcp-file-content"'
- echo "MCP_VARIABLES_OK"Optional:
Prompt used to do above tasks with other GitLab MCP tools
Prepare a test pipeline in my local GDK for testing save_pipeline_job.
Project path: PROJECT_PATH
Use only the GitLab-GDK MCP tools for GitLab operations.
1. Inspect the project and identify its default branch.
2. Create a separate branch named mcp-job-demo from the default branch.
If that branch already exists, choose a unique mcp-job-demo-* name.
3. Use add_commit to create or update .gitlab-ci.yml on that branch
with this configuration:
image: alpine:3
stages:
- test
mcp_plain:
stage: test
when: manual
allow_failure: true
script:
- echo "MCP_PLAIN_OK"
mcp_variables:
stage: test
when: manual
allow_failure: true
script:
- 'test "$E2E_DEFAULT" = "hello-from-mcp"'
- 'test "$E2E_EXPLICIT" = "explicit-value"'
- 'test -f "$E2E_CONFIG"'
- 'test "$(cat "$E2E_CONFIG")" = "mcp-file-content"'
- echo "MCP_VARIABLES_OK"
Reuse any runner tags required by this project's existing CI
configuration. Explain any adjustment to the image or tags.
4. Check whether the commit automatically created a pipeline for that
commit and branch. Reuse it if available. Otherwise, create one
using save_pipeline.
5. Inspect the pipeline with get_pipeline and each job with get_job.
Confirm that:
- The pipeline uses the new branch and commit.
- Both jobs exist and are in the manual state.
- The CI configuration has no validation errors.
Leave both jobs unplayed. Stop after preparing the pipeline.
Return:
- Project path and numeric project ID
- Branch and commit SHA
- Pipeline ID and URL
- Each job's name, integer ID, status, and URL
- Any runner or permission limitation you can establish
Finish by printing these values for my next testing prompt:
Project: PROJECT_PATH
Pipeline: <actual pipeline ID>- Prompting Claude code to use
save_pipeline_joband run manual jobs in the given project and pipeline
Prompt used in above demo video
Test the save_pipeline_job MCP tool against my local GDK.
Project: /root/mcp-tool-test
Pipeline: 571
Perform GitLab operations through the local GitLab MCP connection.
In Claude Code, use GitLab-GDK. In Duo, use the corresponding GitLab
MCP tools, including any gitlab_ prefix.
GDK must already be running and ready before this test starts.
- If GitLab-GDK is disconnected or reports a startup, connection,
timeout, or service-unavailable error, stop and report it immediately.
- Do not start or restart GDK, containers, Rails, Rspack, or runners.
- Do not wait for GDK to boot or retry failed connection attempts.
- If a response indicates GDK is still starting, mark the test BLOCKED
and ask me to rerun it after GDK is ready.
Use MCP tools directly throughout this test. If a required tool is
unavailable, report that instead of substituting shell or API commands.
1. Inspect the pipeline and identify mcp_plain and mcp_variables.
Show their IDs and confirm both are manual.
2. Inspect mcp_plain with get_job, then call save_pipeline_job once
with its integer job ID and the project path. Omit variables.
Show the exact arguments and structured response. Check the job ID,
name, status, stage, pipeline ID, and both URLs.
3. Inspect mcp_variables with get_job, then call save_pipeline_job once
using the numeric project ID as a string and these variables:
[
{"key":"E2E_DEFAULT","value":"hello-from-mcp"},
{"key":"E2E_EXPLICIT","value":"explicit-value","variable_type":"env_var"},
{"key":"E2E_CONFIG","value":"mcp-file-content","variable_type":"file"}
]
Show the exact arguments and structured response.
4. Follow both jobs for up to two minutes. Fetch their logs and verify:
- mcp_plain succeeds and prints MCP_PLAIN_OK.
- mcp_variables succeeds and prints MCP_VARIABLES_OK.
If either remains pending, report its execution test as inconclusive.
5. Once mcp_plain finishes, inspect it again. Record the pipeline's job
IDs, then deliberately attempt save_pipeline_job on that completed
job once. Show the error and verify that no retried job was created.
6. Finish with a short PASS, FAIL, or INCONCLUSIVE table for:
- Playing without variables
- Project path and numeric project ID
- Default environment variable
- Explicit environment variable
- File variable
- Response fields
- Completed-job rejection without retrySpec checks
Run the command below to trigger the specs added/edited in this branch:
bundle exec rspec \
spec/services/mcp/tools/jobs/save_pipeline_job_tool_spec.rb \
spec/services/mcp/tools/jobs/save_pipeline_job_service_spec.rb \
ee/spec/services/mcp/tools/jobs/save_pipeline_job_service_spec.rb \
spec/requests/api/mcp/handlers/call_tool_spec.rb \
spec/requests/api/mcp/handlers/list_tools_spec.rb \
ee/spec/requests/api/mcp/handlers/list_tools_spec.rb \
ee/spec/lib/ai/tool_rules/governable_tools_container_spec.rbMR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.
Related to #597698
