Jobs

The jobs of a pipeline or a project: list them and their trigger jobs, read one and its log, wait for one to finish, play a manual job, retry, cancel or erase one; download a job’s artifact archive, one report or one file of it, or the latest successful archive or file for a ref, keep a job’s artifacts, and delete them for a job or a whole project.

The CI/CD job token scope is here too: which projects and groups may use this project’s job token to reach it, read and changed with the job.token_scope_* actions.

Sample questions

• “Show the log of the failed job in pipeline 1234”
• “Retry job 5678”
• “Download the artifacts of the build job on main”
• “Which projects may use this project’s job token?”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as job.artifacts, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_job with action set to the action’s name, such as artifacts, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_job_artifacts, with its parameters as the arguments.

Availability

Every tier serves the whole group, on self-managed instances and on GitLab.com alike.

Read-only actions: 13 of 25, the ones a deployment in read-only mode keeps.

Actions

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).

Action	Individual
job.artifacts	gitlab_job_artifacts
job.cancel	gitlab_job_cancel
job.delete_artifacts	gitlab_job_delete_artifacts
job.delete_project_artifacts	gitlab_job_delete_project_artifacts
job.download_artifacts	gitlab_job_download_artifacts
job.download_single_artifact	gitlab_job_download_single_artifact
job.download_single_artifact_by_ref	gitlab_job_download_single_artifact_by_ref
job.erase	gitlab_job_erase
job.get	gitlab_job_get
job.keep_artifacts	gitlab_job_keep_artifacts
job.list	gitlab_job_list
job.list_bridges	gitlab_job_list_bridges
job.list_project	gitlab_job_list_project
job.play	gitlab_job_play
job.retry	gitlab_job_retry
job.token_scope_add_group	gitlab_add_group_job_token_allowlist
job.token_scope_add_project	gitlab_add_project_job_token_allowlist
job.token_scope_get	gitlab_get_job_token_access_settings
job.token_scope_list_groups	gitlab_list_job_token_group_allowlist
job.token_scope_list_inbound	gitlab_list_job_token_inbound_allowlist
job.token_scope_patch	gitlab_patch_job_token_access_settings
job.token_scope_remove_group	gitlab_remove_group_job_token_allowlist
job.token_scope_remove_project	gitlab_remove_project_job_token_allowlist
job.trace	gitlab_job_trace
job.wait	gitlab_job_wait

job.artifacts

Download the full artifact archive for a CI job, or one report named by file_type (GitLab 19.4 or later), base64-encoded and truncated at 1MB. Returns: size, content, and truncation flag. See also: job.download_single_artifact, job.keep_artifacts, job.get.

• Meta-tool: gitlab_job, action artifacts
• Individual tool: gitlab_job_artifacts
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID whose artifacts to download
project_id	string/integer	yes	Project ID or URL-encoded path
file_type	string (archive, accessibility, api_fuzzing, browser_performance, cluster_image_scanning, cobertura, codequality, container_scanning, cyclonedx, dast, dependency_scanning, dotenv, jacoco, junit, license_scanning, load_performance, lsif, metrics, performance, requirements, requirements_v2, sarif, sast, secret_detection)	no	Which of the job’s artifacts to download: archive (the default, the zip of the job’s artifacts:paths) or a report type such as junit, cobertura, sast or dotenv. GitLab reads it from 19.4, and an older instance ignores it and answers with the archive

job.cancel

Cancel a CI job. Set force:true to cancel jobs already in a non-cancellable state (requires GitLab v17.2+). Returns: updated job state. See also: job.get, job.retry.

• Meta-tool: gitlab_job, action cancel
• Individual tool: gitlab_job_cancel
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to cancel
project_id	string/integer	yes	Project ID or URL-encoded path
force	boolean	no	Force cancel even if the job is already in a non-cancellable state

job.delete_artifacts

Delete the artifacts for one CI job (destructive). Returns: a success confirmation. See also: job.artifacts, job.get, job.delete_project_artifacts.

• Meta-tool: gitlab_job, action delete_artifacts
• Individual tool: gitlab_job_delete_artifacts
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to delete artifacts from
project_id	string/integer	yes	Project ID or URL-encoded path

job.delete_project_artifacts

Delete every eligible artifact across a project (destructive, irreversible). Returns: a success confirmation. See also: job.delete_artifacts, job.list_project, job.artifacts.

• Meta-tool: gitlab_job, action delete_project_artifacts
• Individual tool: gitlab_job_delete_project_artifacts
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path

job.download_artifacts

Download the latest successful artifacts archive for a ref and job name. Returns: archive size, content, and truncation flag. See also: job.artifacts, job.download_single_artifact, job.get.

• Meta-tool: gitlab_job, action download_artifacts
• Individual tool: gitlab_job_download_artifacts
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
job	string	no	Job name to download artifacts from
ref_name	string	no	Branch or tag name

job.download_single_artifact

Download one artifact file from a job by job_id and artifact_path. Returns: file size, raw content, and truncation flag. See also: job.artifacts, job.download_artifacts, job.get.

• Meta-tool: gitlab_job, action download_single_artifact
• Individual tool: gitlab_job_download_single_artifact
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
artifact_path	string	yes	Path to the artifact file within the archive
job_id	integer	yes	Job ID
project_id	string/integer	yes	Project ID or URL-encoded path

job.download_single_artifact_by_ref

Download one artifact file from the latest successful job on a ref by name and path. Returns: file size, raw content, and truncation flag. See also: job.download_artifacts, job.download_single_artifact, job.get.

• Meta-tool: gitlab_job, action download_single_artifact_by_ref
• Individual tool: gitlab_job_download_single_artifact_by_ref
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
artifact_path	string	yes	Path to the artifact file within the archive
job	string	yes	Job name
project_id	string/integer	yes	Project ID or URL-encoded path
ref_name	string	yes	Branch or tag name

job.erase

Erase a finished CI job’s trace log and artifacts (destructive). Returns: updated job state. See also: job.get, job.trace, job.artifacts.

• Meta-tool: gitlab_job, action erase
• Individual tool: gitlab_job_erase
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to act on
project_id	string/integer	yes	Project ID or URL-encoded path

job.get

Get one CI job. Returns: status, stage, ref, embedded commit/pipeline/project/runner/user objects, timing fields, and failure metadata. See also: job.trace, job.cancel, job.retry.

• Meta-tool: gitlab_job, action get
• Individual tool: gitlab_job_get
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to retrieve
project_id	string/integer	yes	Project ID or URL-encoded path

job.keep_artifacts

Keep a CI job’s artifacts by clearing their expiration. Returns: updated job state. See also: job.artifacts, job.get, job.download_artifacts.

• Meta-tool: gitlab_job, action keep_artifacts
• Individual tool: gitlab_job_keep_artifacts
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to act on
project_id	string/integer	yes	Project ID or URL-encoded path

job.list

List CI jobs for one pipeline with status filters, keyset pagination, and ordering. Returns: job summaries with status, stage, ref, and pipeline association. See also: job.get, job.trace, pipeline.get.

• Meta-tool: gitlab_job, action list
• Individual tool: gitlab_job_list
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
pipeline_id	integer	yes	Pipeline ID to list jobs for
project_id	string/integer	yes	Project ID or URL-encoded path
include_retried	boolean	no	Include retried jobs in the response
order_by	string	no	Column to order keyset-paginated results by
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
scope	string[]	no	Filter by job status: created, pending, preparing, waiting_for_resource, waiting_for_callback, running, success, failed, canceled, canceling, skipped, manual, scheduled
sort	string (asc, desc)	no	Sort order for keyset pagination: asc or desc

job.list_bridges

List CI bridge (trigger) jobs for one pipeline with keyset pagination. Returns: bridge summaries with status and downstream pipeline references. See also: job.list, pipeline.get, job.get.

• Meta-tool: gitlab_job, action list_bridges
• Individual tool: gitlab_job_list_bridges
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
pipeline_id	integer	yes	Pipeline ID to list bridge jobs for
project_id	string/integer	yes	Project ID or URL-encoded path
include_retried	boolean	no	Include retried bridge jobs in the response
order_by	string	no	Column to order keyset-paginated results by
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
scope	string[]	no	Filter by job status: created, pending, preparing, waiting_for_resource, waiting_for_callback, running, success, failed, canceled, canceling, skipped, manual, scheduled
sort	string (asc, desc)	no	Sort order for keyset pagination: asc or desc

job.list_project

List CI jobs in one project with filters, keyset pagination, and ordering. Returns: job summaries, status, stage, ref, and pipeline associations. See also: job.get, job.trace, pipeline.get.

• Meta-tool: gitlab_job, action list_project
• Individual tool: gitlab_job_list_project
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
include_retried	boolean	no	Include retried jobs in the response
order_by	string	no	Column to order keyset-paginated results by
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
scope	string[]	no	Filter by job status: created, pending, preparing, waiting_for_resource, waiting_for_callback, running, success, failed, canceled, canceling, skipped, manual, scheduled
sort	string (asc, desc)	no	Sort order for keyset pagination: asc or desc

job.play

Run a manual CI job with optional variable overrides. Returns: the started job state. See also: job.get, job.retry, job.trace.

• Meta-tool: gitlab_job, action play
• Individual tool: gitlab_job_play
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to run
project_id	string/integer	yes	Project ID or URL-encoded path
job_inputs	object	no	Job input parameters keyed by input name. Values may be string, number, boolean, or array of strings, matching the inputs declared in .gitlab-ci.yml spec:inputs.
job_variables_attributes	object[]	no	Job variables to inject into the manual job run

job.retry

Retry a failed or canceled CI job. Returns: the newly created job state. See also: job.get, job.trace, job.cancel.

• Meta-tool: gitlab_job, action retry
• Individual tool: gitlab_job_retry
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to act on
project_id	string/integer	yes	Project ID or URL-encoded path

job.token_scope_add_group

Add a group to a project’s CI/CD job token allowlist. Returns: the new allowlist entry with source project ID and target group ID. See also: job.token_scope_list_groups, job.token_scope_remove_group, job.token_scope_add_project.

• Meta-tool: gitlab_job, action token_scope_add_group
• Individual tool: gitlab_add_group_job_token_allowlist
• Tier: Free
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
target_group_id	integer	yes	ID of the group to add to the allowlist

job.token_scope_add_project

Add a project to a project’s CI/CD job token inbound allowlist. Returns: the new allowlist entry with source and target project IDs. See also: job.token_scope_list_inbound, job.token_scope_remove_project, job.token_scope_add_group.

• Meta-tool: gitlab_job, action token_scope_add_project
• Individual tool: gitlab_add_project_job_token_allowlist
• Tier: Free
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
target_project_id	integer	yes	ID of the project to add to the allowlist

job.token_scope_get

Get a project’s CI/CD job token access settings. Returns: whether inbound job token access is limited to the allowlist, and the deprecated outbound scope flag. See also: job.token_scope_patch, job.token_scope_list_inbound, job.token_scope_list_groups.

• Meta-tool: gitlab_job, action token_scope_get
• Individual tool: gitlab_get_job_token_access_settings
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path

job.token_scope_list_groups

List groups on a project’s CI/CD job token allowlist. Returns: allowlisted groups with id, name and web URL plus pagination metadata. See also: job.token_scope_add_group, job.token_scope_remove_group, job.token_scope_get.

• Meta-tool: gitlab_job, action token_scope_list_groups
• Individual tool: gitlab_list_job_token_group_allowlist
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string	no	Column to order keyset-paginated results by (e.g. id). Only applies when pagination=‘keyset’.
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction for keyset-paginated results: asc or desc. Only applies when pagination=‘keyset’.

job.token_scope_list_inbound

List projects on a project’s CI/CD job token inbound allowlist. Returns: allowlisted projects with their names, paths, description, visibility, web and clone URLs, topics, counts and namespace, plus pagination metadata. See also: job.token_scope_add_project, job.token_scope_remove_project, job.token_scope_get.

• Meta-tool: gitlab_job, action token_scope_list_inbound
• Individual tool: gitlab_list_job_token_inbound_allowlist
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string	no	Column to order keyset-paginated results by (e.g. id). Only applies when pagination=‘keyset’.
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction for keyset-paginated results: asc or desc. Only applies when pagination=‘keyset’.

job.token_scope_patch

Update a project’s CI/CD job token access settings. Returns: a confirmation that the inbound scope setting was updated. See also: job.token_scope_get, job.token_scope_add_project, job.token_scope_add_group.

• Meta-tool: gitlab_job, action token_scope_patch
• Individual tool: gitlab_patch_job_token_access_settings
• Tier: Free
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
enabled	boolean	yes	Enable or disable the CI/CD job token scope
project_id	string/integer	yes	Project ID or URL-encoded path

job.token_scope_remove_group

Remove a group from a project’s CI/CD job token allowlist. Returns: a success confirmation naming the removed group. See also: job.token_scope_list_groups, job.token_scope_add_group, job.token_scope_remove_project.

• Meta-tool: gitlab_job, action token_scope_remove_group
• Individual tool: gitlab_remove_group_job_token_allowlist
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
target_group_id	integer	yes	ID of the group to remove from the allowlist

job.token_scope_remove_project

Remove a project from a project’s CI/CD job token inbound allowlist. Returns: a success confirmation naming the removed project. See also: job.token_scope_list_inbound, job.token_scope_add_project, job.token_scope_remove_group.

• Meta-tool: gitlab_job, action token_scope_remove_project
• Individual tool: gitlab_remove_project_job_token_allowlist
• Tier: Free
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
target_project_id	integer	yes	ID of the project to remove from the allowlist

job.trace

Get CI job trace output. Returns: text log with truncation metadata when logs exceed limits. See also: job.get, job.retry, job.cancel.

• Meta-tool: gitlab_job, action trace
• Individual tool: gitlab_job_trace
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to get trace log for
project_id	string/integer	yes	Project ID or URL-encoded path

job.wait

Wait for a CI job to finish, polling until terminal state or timeout. Returns: final job snapshot, wait duration, poll count, and timed-out flag. See also: job.get, job.trace, job.retry.

• Meta-tool: gitlab_job, action wait
• Individual tool: gitlab_job_wait
• Tier: Free
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
job_id	integer	yes	Job ID to wait for
project_id	string/integer	yes	Project ID or URL-encoded path
fail_on_error	boolean	no	Return isError when job ends in failed/canceled status (default true)
interval_seconds	integer	no	Polling interval in seconds (5-60, default 10)
timeout_seconds	integer	no	Maximum wait time in seconds (1-3600, default 300)