Configure GITLAB_TOKEN with a group service account

Use a GitLab service account instead of a personal user account for CI Tools automation. A group service account keeps automation independent from employee accounts and can be granted access only to its group and descendant projects.

GitLab service accounts authenticate with personal access tokens. The service account's group or project memberships determine which resources the token can reach, while the token scopes determine which operations it can perform.

Create the service account and token

1. Open the group that owns the projects.
2. Go to Settings > Service accounts and create a service account for CI automation.
3. Add the service account as a member of the group or the individual projects that it must manage. Grant the least role that supports the required operations.
4. From the service account's actions menu, select Manage access tokens and create a token with an expiration date.
5. Select only the required access token scopes:
   • read_api for API reads and pipeline linting.
   • read_repository for repository reads.
   • write_repository for Git pushes without other API writes.
   • read_registry for private container image reads.
   • api when a component creates releases, updates project settings, manages CI/CD variables, or performs other API writes.
6. Copy the token when GitLab displays it. The value cannot be viewed again.

See the GitLab documentation for current service account availability and management.

Store the token as a group variable

In the group, go to Settings > CI/CD > Variables and add a variable with these settings:

Setting	Value
Key	GITLAB_TOKEN
Value	The service account personal access token
Type	Variable
Visibility	Masked and hidden
Protect variable	Enabled when every consuming job runs only on protected branches or tags
Expand variable reference	Disabled

Group variables are inherited by descendant projects. Use a project variable instead when only one project needs the credential. A project variable with the same key overrides the inherited group variable.

Review every pipeline change before running it with the token. Masking and hiding reduce accidental disclosure but cannot prevent a malicious job from sending the token elsewhere. Do not enable debug tracing in jobs that receive secrets.

For current variable behavior and security options, see CI/CD variables and pipeline security.

Select membership and scopes by component

The service account role and token scopes must cover both the component's action and the destination resource. Start with the narrowest access and increase it only when GitLab rejects a required operation.

Use	Components	Typical access
API validation	lint-catalog, lint-pipeline, test-component	Reporter or higher and read_api
Repository or wiki push	git-mirror, gitops, publish-wiki	Permission to push to the destination and write_repository, or api when the workflow also calls the API
Releases and project settings	housekeeping, label, pipeline-components, semantic-release, workflow-gitflow, workflow-trunkbased	Maintainer and api
Token distribution	token-update	Permission to manage destination CI/CD variables and api; restrict this credential particularly carefully
Shared authentication helpers	common	Determined by the components included with it
Renovate	renovate-runner, pipeline-auto-update	Developer or higher in every managed project, with api and read_registry when private images are scanned

api on a service account personal access token includes repository and registry access available to that account. Even so, service account membership remains the effective boundary, so do not add the account to unrelated groups.

Renovate account model

Keep one global Renovate administrator responsible for the shared Renovate service account, runner project, configuration, token rotation, and signing keys. Group owners grant that account the minimum role in groups that opt in to global Renovate.

A group can instead run an isolated Renovate instance:

1. Create a group service account in that group.
2. Grant it access only to the projects Renovate should manage.
3. Create a dedicated runner project and store the account token there as GITLAB_TOKEN.
4. Configure and schedule the renovate-runner component in that project.

Use the group-specific model when isolation or separate maintenance is required. Do not run both the global and group-specific Renovate accounts against the same projects.

Rotate the token

Before the token expires, create or rotate it from the service account's Manage access tokens page and replace the GITLAB_TOKEN variable immediately. Confirm a protected default-branch pipeline succeeds, then revoke any superseded token that remains active.