Skip to content

GitLab CI with id_tokens

GitLab can issue every job a short-lived, signed OIDC token (id_tokens). Entrepot verifies it against the GitLab instance’s JWKS, so pipelines publish packages without any secret stored in CI/CD variables. Which jobs may do what is decided by trust policies — conditions on the token’s claims such as project path, branch and environment — bound to roles.

.gitlab-ci.yml Entrepot (auth.gitlab: issuer, audience)
id_tokens:
ENTREPOT_ID_TOKEN: ── Bearer ──► 1. verify signature (JWKS), aud, expiry
aud: <baseURL> 2. match trust policies (project_path, …)
3. role bindings: policy → role on repos
  1. Trust the GitLab instance in the server configuration (Helm: auth.gitlab):

    auth:
    gitlab:
    - name: gitlab
    issuerURL: https://gitlab.example.com
    audience: https://entrepot.example.com # defaults to server.baseURL

    The audience must equal the aud: you request in .gitlab-ci.yml.

  2. Create a trust policy describing the trusted jobs. All conditions must match; in patterns * stops at / and ** matches across it.

    Terminal window
    curl -fsS -H "Authorization: Bearer $ADMIN" -X POST \
    https://entrepot.example.com/api/v1/gitlab-trust-policies -d '{
    "name": "platform-releases",
    "gitlab": "gitlab",
    "description": "Protected branches and tags of the platform group",
    "conditions": {"project_path": "platform/**", "ref_protected": "true"}
    }'
  3. Bind a role to the policy on the repositories it may publish to:

    Terminal window
    curl -fsS -H "Authorization: Bearer $ADMIN" -X POST \
    https://entrepot.example.com/api/v1/role-bindings -d '{
    "role": "developer", "subjectType": "gitlab_policy",
    "subject": "platform-releases", "repositoryPattern": "*-internal"
    }'

    For jobs that only consume private repositories, bind viewer with a broader policy (for example {"namespace_path": "platform/**"}).

  4. Request the token in the job and use it wherever a client expects a token or password:

    id_tokens:
    ENTREPOT_ID_TOKEN:
    aud: https://entrepot.example.com

The same setup in Terraform: entrepot_gitlab_trust_policy and entrepot_role_binding.

Each job requests ENTREPOT_ID_TOKEN; the username, where a client wants one, can be anything.

publish-npm:
image: node:22
id_tokens:
ENTREPOT_ID_TOKEN:
aud: https://entrepot.example.com
script:
- npm config set registry https://entrepot.example.com/repository/npm-internal/
- npm config set //entrepot.example.com/repository/npm-internal/:_authToken "$ENTREPOT_ID_TOKEN"
- npm ci
- npm publish
rules:
- if: $CI_COMMIT_TAG
build:
image: node:22
id_tokens:
ENTREPOT_ID_TOKEN:
aud: https://entrepot.example.com
script:
- npm config set registry https://entrepot.example.com/repository/npm-group/
- npm config set //entrepot.example.com/repository/npm-group/:_authToken "$ENTREPOT_ID_TOKEN"
- npm ci

Artifacts published by CI jobs record the job’s project, ref, commit and pipeline; the UI shows them on the asset, and the audit log records the job as gitlab:<project_path>@<ref>#<job_id>.

When the GitLab instance also has an API token configured, scan results go back to the pipeline:

  • a commit status entrepot/scan/<repository> — running while scans are outstanding, then failed when the component is quarantined or has unwaived findings at or above the threshold, otherwise success;
  • an MR note on each open merge request for the commit, updated in place on rescans.
auth:
gitlab:
- name: gitlab
issuerURL: https://gitlab.example.com
api:
tokenEnv: ENTREPOT_GITLAB_TOKEN # a token with the "api" scope

With the Helm chart, set feedback: true on the instance and put the token under the key gitlab-token-<name> in auth.existingSecret (or set apiToken).

Symptom Cause
401 Wrong audience (aud must equal the instance’s audience, by default server.baseURL), unknown issuer, or an expired token (long jobs: request the token in the job that uses it).
403 gitlab:…@… is not permitted to write … The job matched no policy, or the policy has no binding with write on that repository. Jobs that match no policy authenticate but get only anonymous permissions.
Works on main, fails on a branch The policy probably requires ref_protected: "true" or a specific ref.
No commit status appears Feedback needs an API token with the api scope for that GitLab instance; errors are logged on the server and never fail a scan.

Check what Entrepot sees for a job’s token:

whoami:
image: curlimages/curl:latest
id_tokens:
ENTREPOT_ID_TOKEN:
aud: https://entrepot.example.com
script:
- 'curl -fsS -H "Authorization: Bearer $ENTREPOT_ID_TOKEN" https://entrepot.example.com/api/v1/me'

The response lists the matched policies and the token’s claims.