helm-external-secrets/docs/api/generator/gitlab.md

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

{% include 'generator-gitlab.yaml' %}

Example ExternalSecret that references the generator:

{% include 'generator-gitlab-example.yaml' %}

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.