Access management

Configuring access management¶

Settings on existing principals (ADR-0005): group and project members, project shares, LDAP and SAML group links, job token allowlists, plus the remaining project deployment surfaces that declare references — remote mirrors, Pages domains, and deploy tokens.

Existing principals only

A declared member whose user does not exist, or a referenced project/group path that does not resolve, is an error in strict mode and a recorded skip in compatible mode, never an implicit creation. Undeclared members are not pruned; only declared memberships are managed.

Example access definition¶

gitlab_settings_groups:
  - path: platform
    members:
      - username: bob
        access_level: developer
        expires_at: "2027-01-01"
    ldap_group_links:
      - cn: gitlab-devs
        provider: main
        group_access: developer
    saml_group_links:
      - saml_group_name: Engineers
        access_level: maintainer

gitlab_settings_projects:
  - path: platform/service
    members:
      - username: alice
        access_level: maintainer
    shared_with_groups:
      - group: platform/qa
        group_access: reporter
    job_token_scope:
      enabled: true
      allowlist:
        - target_project: platform/tool
      groups_allowlist:
        - target_group: platform/ci
    remote_mirrors:
      - url: "https://user:{{ vault_mirror_token }}@mirror.example.com/repo.git"
        enabled: true
    pages_domains:
      - domain: www.example.com
        certificate: "{{ vault_pages_cert }}"
        key: "{{ vault_pages_key }}"
    deploy_tokens:
      - name: registry-reader
        scopes: [read_registry]
        expires_at: "2027-01-01T00:00:00Z"
        token_file: /var/lib/secrets/registry-reader.token

Access Management Spec¶

GitLab API reference

GitLab's API documentation defines the fields:

`members` array of objects Group or project memberships for existing users. Memberships are matched by the resolved user id and are never implicitly pruned. Properties of `members` `username` stringRequired unless alternate identity is set Existing GitLab username, resolved to a user id with exact matching. Declare exactly one of `username` or `user_id`. `user_id` integerRequired unless alternate identity is set Existing GitLab user id. Declare exactly one of `username` or `user_id`. `access_level` string or integerRequired on create or update Stable role name (`guest` 10 through `owner` 50) or its integer value. `expires_at` string (date) Optional membership expiry date; reconciles with drift detection. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `members: - username: bob access_level: developer - username: departed-user state: absent ...`
`deploy_tokens` array of objects Group or project deploy tokens. Tokens are immutable: converging drift recreates the token and rotates its one-time secret. Properties of `deploy_tokens` `name` stringRequired Deploy-token identity. `scopes` array of stringsRequired on create Token scopes. Drift recreates the token. Accepted values for `deploy_tokens[].scopes` `read_repository` — read the repository. `read_registry` — pull container images. `write_registry` — push container images. `read_package_registry` — read packages. `write_package_registry` — publish packages. `read_virtual_registry` — read from a project virtual registry. `write_virtual_registry` — publish through a project virtual registry. At least one scope is required. The two virtual-registry scopes are project-only. `expires_at` string (date-time) Token expiry. Drift recreates the token. `username` string Optional deploy-token username. Drift recreates the token. `token_file` string (absolute path) Controller path that receives the secret exactly once at creation; written `0600` and never logged. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `deploy_tokens: - name: registry-reader scopes: [read_registry] token_file: /var/lib/secrets/registry-reader.token ...`
`projects[].shared_with_groups` array of objects Project shares with existing groups. Shares are add/remove only: changing access reports drift through strict/compatible handling, so remove and re-share to change it. Properties of `projects[].shared_with_groups` `group` stringRequired unless alternate identity is set Existing group path, resolved to an id. Declare exactly one of `group` or `group_id`. `group_id` integerRequired unless alternate identity is set Existing group id. Declare exactly one of `group` or `group_id`. `group_access` string or integerRequired on create Stable access-level name or integer value. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `shared_with_groups: - group: platform/qa group_access: reporter ...`
`groups[].ldap_group_links` array of objects LDAP group links, matched by their LDAP identity and provider. Links are add/remove only; removal sends the identity in the request body as required by GitLab's API. Properties of `groups[].ldap_group_links` `cn` stringRequired unless alternate identity is set LDAP common name. Declare `cn` or `filter`. `filter` stringRequired unless alternate identity is set LDAP filter used instead of `cn`. `provider` stringRequired LDAP provider name; participates in composite matching. `group_access` string or integerRequired on create Stable access-level name or integer value. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `ldap_group_links: - cn: gitlab-devs provider: main group_access: developer ...`
`groups[].saml_group_links` array of objects SAML group links. GitLab can store the same SAML group name under multiple providers; declare the provider to disambiguate those links. Links are add/remove only. Properties of `groups[].saml_group_links` `saml_group_name` stringRequired SAML group name and primary identity. `provider` string Optional provider used to disambiguate duplicate group names; carried on the item route for deletion. `access_level` string or integerRequired on create Stable access-level name or integer value. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `saml_group_links: - saml_group_name: Engineers provider: corp access_level: maintainer ...`
`projects[].job_token_scope.allowlist` array of objects Project entries admitted to the CI/CD job-token scope. Entries are add/remove only; the `enabled` toggle is documented in Integrations and Services. Properties of `projects[].job_token_scope.allowlist` `target_project` stringRequired unless alternate identity is set Existing project path, resolved to an id. Declare exactly one of `target_project` or `target_project_id`. `target_project_id` integerRequired unless alternate identity is set Existing project id. Declare exactly one of `target_project` or `target_project_id`. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `job_token_scope: allowlist: - target_project: platform/tool ...`
`projects[].job_token_scope.groups_allowlist` array of objects Group entries admitted to the CI/CD job-token scope. Entries are add/remove only; the `enabled` toggle is documented in Integrations and Services. Properties of `projects[].job_token_scope.groups_allowlist` `target_group` stringRequired unless alternate identity is set Existing group path, resolved to an id. Declare exactly one of `target_group` or `target_group_id`. `target_group_id` integerRequired unless alternate identity is set Existing group id. Declare exactly one of `target_group` or `target_group_id`. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `job_token_scope: groups_allowlist: - target_group: platform/ci state: absent ...`
`projects[].remote_mirrors` array of objects Push mirrors matched by URL with embedded credentials stripped on both sides because GitLab masks them in responses. Rotate URL credentials by removing and recreating the mirror. Properties of `projects[].remote_mirrors` `url` stringRequired Mirror URL and identity. The full credentialed value is secret: never displayed, compared, or diffed, and carried on every ordinary update. `enabled` boolean Whether the mirror is active; reconciles with drift detection. `only_protected_branches` boolean Mirror only protected branches; reconciles with drift detection. `keep_divergent_refs` boolean Keep divergent refs; reconciles with drift detection. `force_secret_update` boolean Unsupported for mirror URLs because GitLab cannot safely replace credential-bearing URLs in place. Declare `state: absent`, apply, then declare the new URL. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `remote_mirrors: - url: "https://user:{{ vault_token }}@mirror.example.com/repo.git" enabled: true only_protected_branches: true ...`
`projects[].pages_domains` array of objects Custom Pages domains matched by domain name. Properties of `projects[].pages_domains` `domain` stringRequired Domain name and identity. `certificate` string Write-mostly certificate material. GitLab reports expiration, not the material itself. `key` string Write-mostly private-key material. `auto_ssl_enabled` boolean Whether GitLab manages the certificate through automatic SSL; reconciles with drift detection. `state` string Can be one of: `present`, `absent`. Default: `present`	Example: `pages_domains: - domain: www.example.com certificate: "{{ vault_cert }}" key: "{{ vault_key }}" ...`