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.
Trusted GitLab instances
Section titled “Trusted GitLab instances”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.comGET /api/v1/system/info lists the configured instances in
gitlabInstances.
Policies
Section titled “Policies”{ "name": "platform-releases", "gitlab": "gitlab", "description": "Protected refs of projects in the platform group", "conditions": { "project_path": "platform/**", "ref_protected": "true" }}gitlabnames an instance fromauth.gitlab.conditionsmaps claim names to glob patterns. All conditions must match. In patterns*stops at/,**matches across it,?matches one character anda|bmatches 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.
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}.
resource "entrepot_gitlab_trust_policy" "platform_releases" { name = "platform-releases" gitlab = "gitlab" conditions = { project_path = "platform/**" ref_protected = "true" }}
resource "entrepot_role_binding" "platform_releases" { role = "developer" subject_type = "gitlab_policy" subject = entrepot_gitlab_trust_policy.platform_releases.name repository_pattern = "*-internal"}Patterns that work well
Section titled “Patterns that work well”| 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-* |
What happens at runtime
Section titled “What happens at runtime”- 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/mewith the job’s token shows the matchedpoliciesand the token’sclaims— 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.