Build attestations

Build attestations record how an artifact was built: GitLab stores them per project as SLSA provenance, keyed by the digest of the artifact they describe. attestation.list finds the attestations of one subject digest, and attestation.download fetches one of them by its IID.

GitLab serves both routes only where the slsa_provenance_statement feature flag is enabled for the project, and the flag ships disabled, so on an instance where nobody enabled it every project answers 404 whatever the digest or IID. attestation.list reads such a 404 on a project that exists as the API being unavailable and says so, naming the flag and admin.feature_set as the way an administrator enables it, rather than answering an empty list.

Sample questions

• “Which attestations does project 42 hold for this sha256 digest?”
• “Download attestation 3 of project 42”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as attestation.download, 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_attestation with action set to the action’s name, such as download, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_download_attestation, with its parameters as the arguments.

Availability

How many of these actions an instance serves at each tier, out of a total of 2:

• Free: 0
• Premium: 0
• Ultimate: 2

Read-only actions: 2 of 2, 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.

Action	Individual
attestation.download	gitlab_download_attestation
attestation.list	gitlab_list_attestations

attestation.download

Download the raw in-toto attestation bundle for one attestation by IID (Ultimate). Returns: the attestation_iid, the bundle size in bytes, and the base64-encoded content_base64 bundle payload. See also: attestation.list, package.list, project.get.

• Meta-tool: gitlab_attestation, action download
• Individual tool: gitlab_download_attestation
• Tier: Ultimate
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
attestation_iid	integer	yes	Attestation IID (project-scoped)
project_id	string/integer	yes	Project ID or URL-encoded path

attestation.list

List SLSA build provenance attestations for a project artifact by subject digest (Ultimate). Returns: each attestation’s id, iid, project_id, build_id, status, predicate_kind, predicate_type, subject_digest, download_url, and created/updated/expire timestamps, with pagination metadata. See also: attestation.download, package.list, project.get.

• Meta-tool: gitlab_attestation, action list
• Individual tool: gitlab_list_attestations
• Tier: Ultimate
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
subject_digest	string	yes	Hex-encoded SHA-256 digest of the attested artifact: its 64 hex characters, in either case. An OCI-style sha256: prefix is accepted and removed and the hex is lowered before the request
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
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.