Scoping GitLab CI OIDC trust in AWS, Azure and Google Cloud

A GitLab CI job asks for an OIDC token with the id_tokens keyword, then trades that token for cloud credentials. GitLab.com uses one issuer, https://gitlab.com, for every customer, so the cloud can only tell your jobs apart from anyone else’s by reading the token’s claims. AWS lists GitLab among the shared providers whose trust policies must check gitlab.com:sub.[AWS IAM User Guide]

What does a GitLab ID token contain?

The default subject is built from the project path and the ref:[GitLab Docs]

project_path:mygroup/myproject:ref_type:branch:ref:main

Alongside it, the token carries project_id, project_path, namespace_id, namespace_path, ref, ref_type, ref_protected and, when the job names one, environment. GitLab’s docs describe project_id as globally unique for the life of the project and namespace_id as stable while the project stays in its namespace. Paths change when a group or project is renamed or moved.[GitLab Docs]

A project can change the subject format with the ci_id_token_sub_claim_components setting. When it starts with project_id, the subject looks like project_id:67890:ref_type:branch:ref:main.[GitLab Docs] Every trust record for that project then has to use the new form.

The job requests the token and sets its audience:

deploy:
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: sts.amazonaws.com

AWS: sub plus the ID keys

GitLab’s own example trust policy for GitLab.com pins three things: the subject, the group ID and the project ID.[GitLab Docs]

"Condition": {
  "StringEquals": {
    "gitlab.com:aud": "sts.amazonaws.com",
    "gitlab.com:sub": "project_path:mygroup/myproject:ref_type:branch:ref:main",
    "gitlab.com:namespace_id": "12345",
    "gitlab.com:project_id": "67890"
  }
}

GitLab’s example leaves out aud; the version above adds it. GitLab says the audience is often sts.amazonaws.com or your GitLab URL, that it must match the IAM OIDC provider’s configuration, and that using the GitLab URL “might work” but is semantically misleading.[GitLab Docs]

GitLab’s troubleshooting section calls out StringEquals used with a wildcard. It never matches; use StringLike for patterns.[GitLab Docs]

Microsoft Entra: one credential per ref

GitLab’s Azure guide uses the GitLab URL as both the issuer and the audience:[GitLab Docs]

{
  "name": "myproject-main",
  "issuer": "https://gitlab.com",
  "subject": "project_path:mygroup/myproject:ref_type:branch:ref:main",
  "audiences": ["https://gitlab.com"]
}

The job’s id_tokens block must then request aud: https://gitlab.com. Entra matches the subject exactly, allows no wildcards and holds at most 20 credentials per app or user-assigned managed identity,[Microsoft Learn] so each branch or tag that deploys needs its own credential.

Google Cloud: a condition on the group

Google requires an attribute condition for GitLab.com providers that restricts tokens to your group:[Google Cloud documentation]

assertion.namespace_id == '12345'

Its example optionally adds && assertion.environment == 'production'. Because the condition reads IDs, it keeps working through renames and doesn’t depend on the subject format. Narrow it further to the project and ref if the IAM binding doesn’t:

assertion.namespace_id == '12345' &&
assertion.project_id == '67890' &&
assertion.ref == 'main'

Checklist

• The trust record names your group and project, never project_path:* or a whole group with *.
• On GitLab.com AWS roles, gitlab.com:namespace_id and gitlab.com:project_id are checked.
• The audience in id_tokens matches the cloud side.
• Deploy roles trust protected branches or tags only.
• Trust records are removed when a project is archived, renamed or moved.

Test a policy with the GitLab preset in the OIDC trust checker. For why path-based trust is risky after a project is renamed or deleted, see subject recycling.