GitLab bot accounts

Set up a GitLab bot user for API automation, with 2FA and optional SSO.

Problem

You want to automate a process using the GitLab API (pipelines, projects, merge requests, work items, or other HTTP APIs) under a stable non-human identity.

Doing that in CKI means creating a dedicated bot user, storing its personal access token in Hashicorp Vault with metadata in secrets.yml, and wiring two-factor authentication, and usually Red Hat SSO via Kerberos keytab, to grant access to projects under the redhat namespace .

Service accounts versus bot (user) accounts

GitLab offers service accounts for scoped automation. The bot users in this guide are ordinary GitLab members backed by Red Hat SSO, because they require access to multiple projects.

Feature GitLab service account CKI bot (user) account
What it is Non-person identity for automation (instance, group, or project scope). Team-owned user account. Same capabilities as a human member where policy allows.
Where it is managed In GitLab: Admin → Service accounts, or Settings → Service accounts on a group or project. GitLab membership like any other user. For redhat namespace access, read about Red Hat SSO in the internal documentation.
How it authenticates Personal access token (PAT) only; cannot sign in to the web UI. Password-based or SSO (Kerberos keytab) and 2FA on the user record, plus a PAT for API calls.
How it is created Add service account on the Service accounts page in GitLab groups or projects. Standard GitLab user creation, or use SSO, then setup 2FA.
Quota and limits Does not use a seat (see GitLab service accounts). Quotas depend on plan (e.g. caps per top-level group on Free; see GitLab docs). Counts as a normal user for billing and seats. Limits 5 “email+suffix” aliases, aka detumbled-email, relevant when using Google Group.
Best when Automation should stay inside one group or project subtree and only needs API/registry-style access. You need broad access, membership across many groups and projects, or Red Hat SAML permissions.

Prerequisites

Define the scope of the service PAT (personal access token) based on the table above. If you decide for a bot (user) account, ensure you have the necessary permissions required for Handling secrets, or get assistance from someone in cki-infra-team.

1. Create the GitLab account

  1. Use an email address that is an alias of a CKI Google Groups bot mailbox, typically cki-ci-bot+<purpose>@redhat.com (plus-addressing). GitLab applies a limit on how many accounts can share the same normalized (“detumbled”) address; that is why CKI maintains more than one bot-related group. Confirm current policy with the team before adding many new bots.
  2. Set an initial password with a strong generator (for example diceware). You will need the password briefly for GitLab UI steps, before relying on SSO, to setup 2FA and create the first PAT.

2. Enable two-factor authentication (Bitwarden)

Bitwarden is an open-source, end-to-end encrypted password manager with a web client. It is acceptable for TOTP secrets without a hardware token.

Configure GitLab

  1. Open your avatar (upper-right) → Edit profile → Account.
  2. Under Two-factor authentication, choose Enable Two-factor Authentication.
  3. In One-time password authenticator, select Register authenticator.
  4. Copy the OTP Secret Key and keep the GitLab tab open.

See also GitLab: Register an OTP authenticator.

Configure Bitwarden

  1. Create an account at vault.bitwarden.com if needed.
  2. Click New → Login.
  3. Name the entry (for example GitLab <bot-name>).
  4. Under Login credentials, paste the OTP secret into Authenticator Key.
  5. Save. To read codes: use the row menu → Copy verification code, or open the item and copy Verification code (TOTP).

Finish in GitLab

Paste the current six-digit code from Bitwarden, enter your GitLab password in the required field (use I forgot my password if needed), and select Register with two-factor app.

3. Personal access token and secrets

  1. In GitLab, create a personal access token with the scopes required for your use-case, including token rotation.

  2. Add the token to Hashicorp Vault and secrets.yml following [Handling secrets]:

    TOKEN_NAME=COM_GITLAB_TOKEN_EXAMPLE_BOT/$(date +%s)
cki_edit_secret ${TOKEN_NAME}

  3. Set only two metadata fields by hand, then let the credential manager fill the rest:

    cki_edit_secret ${TOKEN_NAME}#token_type gitlab_personal_token
cki_edit_secret ${TOKEN_NAME}#instance_url https://gitlab.com
python3 -m cki_tools.credentials.manager update --token-name ${TOKEN_NAME}

    Full field semantics are in the credential manager documentation under GitLab personal access tokens.

  4. For the first version, ensure deployed: true matches your rotation story.

4. Validate token rotation

Ensure the token is rotatable using the three-step rotation described in Handling secrets → Rotating managed secrets: prepare, then switch, then clean, with merges and deployments between steps as documented.

In case you need to access the redhat namespace from a bot account, you can setup Red Hat SSO. See also how we maintain a fresh SAML token with cki.cki_tools.gitlab_sso_login.