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 reposSet up
Section titled “Set up”-
Trust the GitLab instance in the server configuration (Helm:
auth.gitlab):auth:gitlab:- name: gitlabissuerURL: https://gitlab.example.comaudience: https://entrepot.example.com # defaults to server.baseURLThe
audiencemust equal theaud:you request in.gitlab-ci.yml. -
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"}}' -
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
viewerwith a broader policy (for example{"namespace_path": "platform/**"}). -
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.
Publishing examples
Section titled “Publishing examples”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_TAGpublish-pypi: image: python:3.12 id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - pip install build twine - python -m build - twine upload --repository-url https://entrepot.example.com/repository/pypi-internal/ -u gitlab-ci -p "$ENTREPOT_ID_TOKEN" dist/* rules: - if: $CI_COMMIT_TAGpush-image: image: docker:27 services: [docker:27-dind] id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - echo "$ENTREPOT_ID_TOKEN" | docker login entrepot.example.com -u gitlab-ci --password-stdin - docker build -t entrepot.example.com/docker-internal/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHA . - docker push entrepot.example.com/docker-internal/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHApublish-chart: image: alpine/helm:3 id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - helm package ./chart --version "$CI_COMMIT_TAG" - 'curl -f --data-binary @$(ls *.tgz) -H "Authorization: Bearer $ENTREPOT_ID_TOKEN" https://entrepot.example.com/repository/helm-internal/api/charts' rules: - if: $CI_COMMIT_TAGOCI instead: helm registry login entrepot.example.com -u gitlab-ci -p "$ENTREPOT_ID_TOKEN"
then helm push chart.tgz oci://entrepot.example.com/docker-internal/charts.
publish-deb: image: curlimages/curl:latest id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - 'curl -f -H "Authorization: Bearer $ENTREPOT_ID_TOKEN" -T dist/$CI_PROJECT_NAME.deb "https://entrepot.example.com/repository/apt-internal/$CI_PROJECT_NAME.deb?distribution=stable&component=main"'publish-rpm: image: curlimages/curl:latest id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - 'curl -f -H "Authorization: Bearer $ENTREPOT_ID_TOKEN" -T dist/$CI_PROJECT_NAME.rpm "https://entrepot.example.com/repository/yum-internal/$CI_PROJECT_NAME.rpm"'upload: image: curlimages/curl:latest id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - 'curl -f -H "Authorization: Bearer $ENTREPOT_ID_TOKEN" --upload-file dist/app.tar.gz "https://entrepot.example.com/repository/files/$CI_PROJECT_PATH/$CI_COMMIT_SHORT_SHA/app.tar.gz"'Consuming private repositories
Section titled “Consuming private repositories”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 citest: image: python:3.12 id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - pip install --index-url "https://gitlab-ci:$ENTREPOT_ID_TOKEN@entrepot.example.com/repository/pypi-group/simple/" -r requirements.txttest: image: docker:27 services: [docker:27-dind] id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - echo "$ENTREPOT_ID_TOKEN" | docker login entrepot.example.com -u gitlab-ci --password-stdin - docker pull entrepot.example.com/docker/team/base:latestThe job’s own image: is pulled by the runner, not the job; configure the
runner’s DOCKER_AUTH_CONFIG or use an anonymously readable repository for
job images.
build: image: debian:12 id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - printf 'machine entrepot.example.com/repository/apt-internal/\nlogin gitlab-ci\npassword %s\n' "$ENTREPOT_ID_TOKEN" > /etc/apt/auth.conf.d/entrepot.conf - echo "deb [signed-by=/etc/apt/keyrings/entrepot-apt-internal.gpg] https://entrepot.example.com/repository/apt-internal stable main" > /etc/apt/sources.list.d/apt-internal.list - apt-get update && apt-get install -y mypkg(Fetch public.gpg into /etc/apt/keyrings/ first, as in Apt.)
deploy: image: alpine/helm:3 id_tokens: ENTREPOT_ID_TOKEN: aud: https://entrepot.example.com script: - helm repo add internal https://entrepot.example.com/repository/helm/ --username gitlab-ci --password "$ENTREPOT_ID_TOKEN" - helm upgrade --install my-release internal/mychartProvenance and scan feedback
Section titled “Provenance and scan feedback”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>—runningwhile scans are outstanding, thenfailedwhen the component is quarantined or has unwaived findings at or above the threshold, otherwisesuccess; - 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" scopeWith 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).
Troubleshooting
Section titled “Troubleshooting”| 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.