GitLab CI jobs can request OIDC ID tokens. The issuer is your GitLab instance (https://gitlab.com or self-hosted). Jobs set their own audience in id_tokens. GitLab has no platform default audience.
Docs and discovery
| Docs | ID tokens in GitLab CI |
| Issuer | Your instance URL, usually https://gitlab.com |
| Discovery | https://gitlab.com/.well-known/openid-configuration or <instance>/.well-known/openid-configuration |
GitLab puts the branch or tag name in ref and sets ref_type to branch or tag. There is no refs/heads prefix.
Token
| Issuer | The GitLab instance |
| Audience | Whatever the job requests in id_tokens |
| Project | project_path (group/project, subgroups allowed) |
| Branch or tag | ref plus ref_type |
| Environment | environment |
A token names either a ref or an environment, not both.
Fields
| Field | Claim | Required | Validation |
|---|---|---|---|
| Instance | iss | Yes | https:// URL with no query or fragment. |
| Group or username | project_path | Yes | Joined with the project. Subgroups work (acme/platform). |
| Project | project_path | Yes | Last segment of project_path. |
| Audience | aud | Yes | The aud the job requests. Use a value unique to your app. |
| Scope by | No | Any ref, or a branch, tag, or environment. | |
| Branch / tag / environment | ref and ref_type, or environment | When scoped | Shown when you pick a scope. |
| Additional claims | other | No | Cannot reuse aud, project_path, ref, ref_type, or environment. |
You can paste a GitLab link into Group. A /-/tree/<branch> or /-/tags/<tag> link also sets the scope. Self-hosted links need /-/ in the path.
Example policy
{
issuer: "https://gitlab.com",
claims: {
aud: ["https://app.example.com"],
project_path: ["acme/platform/web"],
ref: ["v1.0.0"],
ref_type: ["tag"],
},
}Add a field
Edit components/oidc/provider-gitlab.tsx after install. For a one-off claim, use Additional claims. For its own input, add it to Fields (or schema), DEFAULTS, compile, parse, FIRST_CLASS_CLAIMS, and the form.
See Add a field.