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

Screenshot-1322

How to set up and validate locally

MCP tool registration

  1. Connect Claude Code with GDK MCP
  2. Trigger the command /mcp in Claude Code CLI and then navigate to View tools to check if the save_pipeline_job MCP tool is now registered or not.

MCP tool functioning with prompt

  1. 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>
  1. Prompting Claude code to use save_pipeline_job and 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 retry

Spec 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.rb

MR 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

Edited by Dhairya Majmudar

Merge request reports

Loading
Loading