Skip to content

GitLab trust policies

A trust policy describes a set of GitLab CI jobs by conditions over the claims in their id_token. When a job authenticates, Entrepot matches its token against every policy for that GitLab instance; role bindings with subjectType: gitlab_policy then grant the matched policies their roles.

Instances are declared in server configuration, not through the API, because they define whose signatures Entrepot accepts:

auth:
gitlab:
- name: gitlab # referenced by trust policies
issuerURL: https://gitlab.example.com # the iss claim; JWKS is discovered from it
audience: https://entrepot.example.com # the aud jobs must request (default: server.baseURL)
- name: gitlab-com
issuerURL: https://gitlab.com
audience: https://entrepot.example.com

GET /api/v1/system/info lists the configured instances in gitlabInstances.

{
"name": "platform-releases",
"gitlab": "gitlab",
"description": "Protected refs of projects in the platform group",
"conditions": {
"project_path": "platform/**",
"ref_protected": "true"
}
}
  • gitlab names an instance from auth.gitlab.
  • conditions maps claim names to glob patterns. All conditions must match. In patterns * stops at /, ** matches across it, ? matches one character and a|b matches either alternative.

Useful claims:

Claim Example Notes
project_path platform/payments/api full path of the project
namespace_path platform/payments group or user namespace
ref main, v1.4.0 branch or tag name
ref_type branch, tag
ref_protected "true" only protected branches and tags
environment production set when the job declares environment:
pipeline_source push, merge_request_event, schedule

Any other claim in GitLab’s id_token can be used the same way.

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",
"conditions": {"project_path": "platform/**", "ref_protected": "true"}
}'
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"
}'

Update with PUT /api/v1/gitlab-trust-policies/{name}.

Goal Conditions
Any pipeline in a group may read private repositories {"namespace_path": "platform/**"} → viewer on *-group
Only protected refs may publish {"project_path": "platform/**", "ref_protected": "true"} → developer on *-internal
Only tagged releases publish to a release repository {"project_path": "platform/**", "ref_type": "tag", "ref": "v*"} → developer on npm-releases
Deployments to production may pull production images {"environment": "production"} → viewer on docker-prod
One project owns one repository {"project_path": "platform/payments/api"} → maintainer on payments-*
  • Tokens with the wrong audience, an unknown issuer or an expired signature get 401.
  • A valid token that matches no policy authenticates, but gets no permissions beyond anonymous access.
  • GET /api/v1/me with the job’s token shows the matched policies and the token’s claims — the quickest way to debug a policy.
  • The audit log records the job as gitlab:<project_path>@<ref>#<job_id>, and published assets record the project, ref, commit and pipeline.