Skip to content

Gitlab

GitLab Deploy Token Generator

The GitLab Deploy Token generator creates GitLab deploy tokens for a project or a group. A deploy token gives read or write access to a project's repository, container registry, and package registry, which makes it well suited for pulling images or packages from automation.

The generated secret contains two keys:

  • username: the deploy token username (the value of spec.username, or the gitlab+deploy-token-{n} value GitLab assigns when username is omitted).
  • token: the deploy token value.

Authentication

The generator authenticates against the GitLab API with an access token (personal, group, or project) that has the api scope and at least the Maintainer role on the target project (or Owner on the target group). Store that token in a Kubernetes secret and reference it from spec.auth.token.secretRef.

kubectl create secret generic gitlab-api-token --from-literal=token=glpat-xxxxxxxxxxxx

Target

Set exactly one of spec.projectID or spec.groupID. Both accept either a numeric ID or an unescaped path such as group/project, the generator URL-escapes paths before calling the API, so do not pre-encode them. Setting both, neither, or an empty string is rejected by the CRD.

Scopes

spec.scopes requires at least one of: read_repository, read_registry, write_registry, read_package_registry, write_package_registry. Projects additionally support read_virtual_registry and write_virtual_registry.

Token lifecycle

GitLab deploy tokens are persistent: unlike short-lived tokens they are not garbage-collected by GitLab on their own. This generator therefore records the created token ID in its generator state and revokes the previous token whenever the value is regenerated (on refresh) and when the consuming ExternalSecret is deleted. Set spec.expiresAt if you also want GitLab to expire the token server-side as a backstop.

Example Manifest

# 1. Create a GitLab access token (personal, group, or project) with the `api`
#    scope and at least the Maintainer role on the target project / group.
#    https://docs.gitlab.com/api/deploy_tokens/
# 2. Store it in a Kubernetes secret, e.g.
#    kubectl create secret generic gitlab-api-token --from-literal=token=glpat-xxxx
---
apiVersion: generators.external-secrets.io/v1alpha1
kind: GitlabDeployToken
metadata:
  name: gitlab-deploy-token
spec:
  url: "" # Optional, defaults to https://gitlab.com
  projectID: "42" # Numeric ID or unescaped path e.g. group/project. Mutually exclusive with groupID.
  # groupID: "7"   # Use instead of projectID to create a group deploy token.
  name: "eso-managed"
  scopes:
    - read_repository
    - read_registry
  expiresAt: "2027-01-01T00:00:00Z" # Optional
  username: "eso" # Optional, GitLab defaults to gitlab+deploy-token-{n}
  auth:
    token:
      secretRef:
        name: gitlab-api-token
        key: token

Example ExternalSecret that references the generator:

---
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: gitlab-deploy-token
spec:
  refreshInterval: "1h"
  target:
    name: gitlab-deploy-token # Name for the secret to be created on the cluster
  dataFrom:
    - sourceRef:
        generatorRef:
          apiVersion: generators.external-secrets.io/v1alpha1
          kind: GitlabDeployToken
          name: gitlab-deploy-token

Notes

  • The access token used for authentication is never written to the target secret; only the generated deploy token is.
  • Each refresh creates a new deploy token and revokes the prior one, so the token value rotates on every refreshInterval.