Attestations API

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Experiment

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

Use this API to interact with provenance attestations.

Provenance attestations

Some endpoints return Sigstore bundles as part of the response. For attestations that use the SIGSTORE attestation method, you can verify these bundles with glab or cosign. For more information on provenance, see SLSA provenance specification.

List all attestations

Lists all attestations for a specified project and SHA-256 hash.

GET /projects/:id/attestations/:subject_digest

Supported attributes:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
subject_digest string yes The hex encoded SHA-256 hash of the artifact

If successful, returns 200 OK and the following response attributes:

Attribute Type Description
build_id integer ID of the CI/CD job that produced the attestation.
created_at datetime Date and time the attestation was created.
download_url string URL to download the attestation bundle.
expire_at datetime Date and time the attestation expires.
id integer ID of the attestation.
iid integer Internal ID of the attestation in the project.
predicate_kind string Kind of predicate. Possible values: provenance or sbom.
predicate_type string URI of the predicate type.
project_id integer ID of the project.
signing_method string Attestation method used to sign the attestation. Possible values: sigstore or local_ca. If ATTEST_METHOD is not set, defaults to local_ca, except for public projects on GitLab.com, which default to sigstore.
status string Status of the attestation. Possible values: success or error.
subject_digest string Hex-encoded SHA-256 hash of the artifact.
updated_at datetime Date and time the attestation was last updated.

Example request:

shell
curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects/namespace%2fproject/attestations/5db1fee4b5703808c48078a76768b155b421b210c0761cd6a5d223f4d99f1eaa"

Example response:

json
[
  {
    "id": 1,
    "iid": 1,
    "created_at": "2025-10-07T20:59:27.085Z",
    "updated_at": "2025-10-07T20:59:27.085Z",
    "expire_at": "2027-10-07T20:59:26.967Z",
    "project_id": 1,
    "build_id": 1,
    "status": "success",
    "predicate_kind": "provenance",
    "predicate_type": "https://slsa.dev/provenance/v1",
    "subject_digest": "76c34666f719ef14bd2b124a7db51e9c05e4db2e12a84800296d559064eebe2c",
    "signing_method": "sigstore",
    "download_url": "https://gitlab.example.com/api/v4/projects/1/attestations/1/download"
  }
]

Download an attestation

Downloads a specific provenance Sigstore bundle by project and attestation IID. The bundle itself is returned in the response body. For more information on this file format, see the relevant Sigstore documentation.

GET /projects/:id/attestations/:attestation_iid/download

Supported attributes:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
attestation_iid integer yes The IID of the attestation, as returned by the list attestations API endpoint.

Example request:

shell
curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects/72356192/attestations/1/download"

Example response:

json
{
  "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
  "verificationMaterial": {
    "certificate": {
      "rawBytes": "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"
    },
    "tlogEntries": [
[...]

List all signing certificates

Lists all unexpired signing certificates for a specified project. Signing certificates are the certificate authority (CA) certificates that GitLab creates for the project and uses for the LOCAL_CA attestation method. GitLab never returns the CA private key. To verify LOCAL_CA attestations, trust all returned certificates, including inactive ones.

GET /projects/:id/attestations/signing_certificates

Supported attributes:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project

Use the page and per_page pagination parameters to control the pagination of results.

If successful, returns 200 OK and the following response attributes:

Attribute Type Description
active boolean If true, GitLab uses this CA to issue certificates for new attestations. A project has at most one active certificate.
certificate string PEM-encoded CA certificate, which contains the CA public key.
created_at datetime Date and time the certificate was created.
expires_at datetime Date and time the certificate expires.
id integer ID of the signing certificate.

Example request:

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/attestations/signing_certificates"

Example response:

json
[
  {
    "id": 1,
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIBszCCAVqgAwIBAgIUJ...\n-----END CERTIFICATE-----\n",
    "active": true,
    "expires_at": "2036-10-22T07:08:25.000Z",
    "created_at": "2026-10-22T07:08:25.643Z"
  }
]