<GitLabAuth>

The <GitLabAuth> block authenticates to GitLab.

It detects an existing login from the GITLAB_TOKEN environment variable or the GitLab CLI. Users can also authenticate manually with a Personal Access Token. Once authenticated, the GITLAB_TOKEN/GITLAB_USER credentials are available to subsequent Command, Check, and GitClone blocks.

GitLab has no OAuth device flow here (there is no registered Gruntwork GitLab app), so authentication is via PAT, the glab CLI, or the GITLAB_TOKEN environment variable.

Basic usage

<GitLabAuth
  id="git-auth"
  title="Authenticate to GitLab"
  description="Sign in to access private repositories"
/>

<Command
  id="clone-repo"
  gitAuthId="git-auth"
  title="Clone Repository"
  command="git clone https://gitlab.com/gruntwork-io/runbooks.git"
/>

By default, Runbooks detects and uses credentials from, in order:

The GITLAB_TOKEN environment variable
The GitLab CLI (glab auth token). glab auth login writes the token to glab’s config.yml, which Runbooks reads directly when glab auth token returns nothing, for example when the glab binary is not on PATH.

If no credentials are detected, the user authenticates manually with a Personal Access Token. Set detectCredentials={false} to always require one, even when the user is logged in with glab. See Disabling detection.

Runbooks sends an environment token, prefixed or not, only over HTTPS. A glab token goes only to the host glab stored it for, and only over HTTPS unless glab itself uses HTTP for that host (api_protocol: http). For a plain http:// instance the environment token is skipped, and so is the glab token unless glab uses HTTP for that host. The user then pastes a Personal Access Token.

The block can authenticate to a plain http:// instance. GitClone and GitLabMergeRequest, including its label lookup, send the session token only over HTTPS. On such an instance the token is available only to Command and Check scripts as GITLAB_TOKEN.

Prefixed environment variables

Add { env: { prefix: 'PREFIX_' } } to detectCredentials to read a namespaced token instead of the standard variables. For example, you can use a CI token so it is never confused with a personal GITLAB_TOKEN:

<GitLabAuth
  id="gitlab-auth"
  detectCredentials={[{ env: { prefix: 'CI_' } }, 'cli']}
/>

With a prefix, Runbooks reads only CI_GITLAB_TOKEN, then CI_GITLAB_ACCESS_TOKEN. It never falls back to the unprefixed variables. The prefix may contain only uppercase letters, digits and underscores. It must start with a letter and end with an underscore (for example CI_ or PROD_). Any other prefix is rejected.

An environment token is only ever sent to one GitLab host. For a prefixed token, that host comes from the prefixed host variables: CI_GITLAB_HOST, then CI_GITLAB_URI, then CI_GL_HOST. If none is set, the host is gitlab.com. The unprefixed GITLAB_HOST does not apply. If the block authenticates to any other host, the prefixed token is skipped.

The prefixed host variables only limit where the token may be sent. They do not choose the host the block authenticates to, which still comes from the host picker or the host prop. For a self-managed instance, set host to the same host as CI_GITLAB_HOST so the prefixed token is used.

On success the token is saved to the session as GITLAB_TOKEN, as with any other source, so downstream blocks don’t need to know the prefix.

Props

<GitLabAuth> accepts the same props as <GitAuth> except provider and hideProviderSelect (which are fixed to gitlab and true). The most common are id (required), title, description, detectCredentials, and inputsId. title defaults to GitLab Authentication. For a self-managed GitLab instance, add host or instanceUrl; see Self-managed GitLab.

Downstream references

Reference the block from other blocks with gitAuthId (provider-agnostic). The githubAuthId prop is GitHub-only and cannot reference a GitLab block. See Explicit block references.

For full details on detection, scopes, and security, see the <GitAuth> documentation.