<GitAuth>

The <GitAuth> block authenticates the user to GitHub or GitLab. A dropdown on the block selects the provider.

It detects whether the user is already authenticated by checking their environment variables and the provider’s CLI (gh for GitHub, glab for GitLab). Users can also authenticate manually. GitHub supports OAuth and a Personal Access Token (PAT). GitLab supports a PAT. Once authenticated, the credentials are available to later Command, Check, and GitClone blocks.

Basic usage

Default to GitHub and let the user pick the provider from the dropdown:

<GitAuth id="git-auth" title="Authenticate to Git" />

Pre-select GitLab and hide the dropdown so the runbook is GitLab-only:

<GitAuth
  id="git-auth"
  provider="gitlab"
  hideProviderSelect
  title="Authenticate to GitLab"
/>

<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 these sources, in order:

1. Environment variables. For GitHub, GITHUB_TOKEN or GH_TOKEN, and GH_ENTERPRISE_TOKEN or GITHUB_ENTERPRISE_TOKEN for GitHub Enterprise Server. For GitLab, GITLAB_TOKEN.
2. The provider CLI. gh auth token --hostname <host> for GitHub, or glab auth token for GitLab. For GitLab, Runbooks also reads glab’s config.yml, where glab auth login stores the token, when glab auth token returns nothing, for example when the glab binary is not on PATH.

If no credentials are detected, users authenticate manually.

To read prefixed variables such as CI_GITHUB_TOKEN or CI_GITLAB_TOKEN, add { env: { prefix: 'CI_' } } to detectCredentials. See <GitHubAuth> and <GitLabAuth> for the variables each provider reads.

detectCredentials can also list { block: 'block-id' } to take the token another block wrote to its outputs (GITHUB_TOKEN/GH_TOKEN or GITLAB_TOKEN), or the credential another <GitAuth> block authenticated. Sources are tried in the order you list them. If that block has not run yet, the block shows Waiting for “block-id” to run… and detection pauses there without moving to a later source. If the block ran without leaving a usable token, detection moves on to the next source.

Disabling detection

Set detectCredentials={false} to have the user always sign in on the block itself:

<GitAuth id="git-auth" detectCredentials={false} />

The block then never uses a token from an environment variable or from the gh or glab CLI, even when the user is already logged in with one, and it never suggests logging in with the CLI. It tells the user that the runbook doesn’t use existing credentials and to sign in below, with no Check again button and no help on authenticating automatically. The host picker still lists the hosts Runbooks knows about, so the user can choose where to sign in, but it has no Reload button and doesn’t mark which hosts have credentials.

Providers

Provider	Methods	CLI	Token env var	OAuth
github (default)	OAuth, PAT, CLI, env	gh	GITHUB_TOKEN or GH_TOKEN, and GH_ENTERPRISE_TOKEN for GHES	Yes (enterprise hosts need oauthClientId)
gitlab	PAT, CLI, env	glab	GITLAB_TOKEN	No

Note

There is no registered Gruntwork GitLab app, so GitLab has no OAuth flow and authenticates via a Personal Access Token, the glab CLI, or the GITLAB_TOKEN environment variable. When GitLab reports a token’s scopes, the success card lists them and warns if the token has neither api nor write_repository, since pushing branches and opening merge requests may fail.

Hosts

Both providers support more than their public SaaS host. Set host to pin the block to one host and hide the host picker. With host unset, the block offers a picker whenever more than one host is available.

Provider	Default host	Other hosts	Picker lists
github	github.com	GitHub Enterprise Server (such as github.example.com) and GHE.com data-residency tenants (such as acme.ghe.com)	Hosts from gh’s hosts.yml (gh auth login --hostname <host>), GH_HOST, the session host, recently used hosts
gitlab	gitlab.com	Self-managed GitLab instances (such as gitlab.example.com)	Hosts from glab’s config.yml, hosts named by environment variables, the session host, recently used hosts

<GitAuth
  id="git-auth"
  provider="github"
  hideProviderSelect
  host="github.example.com"
  oauthClientId="0a1b2c3d4e5f6a7b8c9d"
/>

For GitHub, the picker’s initial host is the host the user last picked if a credential for it is still available, then GH_HOST, then github.com. Each environment token is bound to a single host. GITHUB_TOKEN and GH_TOKEN go to GH_HOST when it is github.com or a *.ghe.com tenant, and to github.com otherwise. GH_ENTERPRISE_TOKEN and GITHUB_ENTERPRISE_TOKEN go only to the Enterprise Server host GH_HOST names.

The Gruntwork OAuth app only exists on github.com. On an enterprise host, Sign in with GitHub needs oauthClientId set to the client ID of an OAuth app registered on that instance with device flow enabled. Without one, the block offers a personal access token and the GitHub CLI, or only the token when detectCredentials={false}, and explains why.

See GitHub Enterprise support on the <GitHubAuth> page for the host, environment variable, API URL, and OAuth details.

Self-managed GitLab

A GitLab block can authenticate to your own GitLab instance in three ways:

• Host picker. The block lists the GitLab hosts it knows about: the hosts you are logged into with glab (glab auth login --hostname gitlab.example.com), the host your environment names, and instances you entered before. It detects credentials for the host you pick and remembers the pick.
• Instance URL field. The Personal Access Token form has an editable GitLab Instance URL field, for example https://gitlab.example.com. Leave it blank for gitlab.com. Picking Other instance in the host picker takes you to it.
• Props. host pins the block to one instance and hides the host picker. instanceUrl pre-fills the Instance URL field. See Props.

A filled-in instance URL, whether typed or set with instanceUrl, takes precedence over host and the host picker. Picking a host in the picker clears the field.

The GITLAB_TOKEN environment variable is used for one instance only. That instance is the host named by GITLAB_HOST, GITLAB_URI or GL_HOST, checked in that order, or gitlab.com when none is set. Runbooks never sends the token to any other host, or over plain http://, so to have it detected for a self-managed instance, also set GITLAB_HOST. A prefixed token ({ env: { prefix } }) is bound by the prefixed host variables. See <GitLabAuth>.

Props

Prop	Type	Required	Default	Description
id	string	Yes	-	Unique block ID.
provider	'github' | 'gitlab'	No	'github'	The initially selected provider.
hideProviderSelect	boolean	No	false	When true, hide the provider dropdown and lock the provider to provider.
title	string	No	"Git Authentication"	Block title (supports template expressions).
description	string	No	-	Block description (supports template expressions).
host	string	No	-	Pins the host and hides the host picker. GitHub: github.com, a GitHub Enterprise Server host (github.example.com), or a GHE.com tenant (acme.ghe.com). GitLab: gitlab.com or a self-managed instance. See Hosts.
oauthClientId	string | Record<string, string>	No	Gruntwork’s app (github.com only)	Custom GitHub OAuth App client ID. A string applies to host when set, otherwise to github.com. A map is keyed by host. Required for OAuth on GitHub Enterprise hosts. GitHub only.
oauthScopes	string[]	No	['repo'] (GitHub)	OAuth scopes to request.
instanceUrl	string	No	-	GitLab only. The starting value of the editable GitLab Instance URL field, such as https://gitlab.example.com. Credentials are detected and tokens validated against this instance. Takes precedence over host.
detectCredentials	false | GitCredentialSource[]	No	['env', 'cli']	Credential detection sources, applied to the selected provider. Set to false to disable. See Disabling detection.
defaultTab	'oauth' | 'pat'	No	'oauth' (GitHub), 'pat' (GitLab)	Which authentication tab the block opens on. GitLab has no OAuth flow, so 'oauth' falls back to 'pat' there. Re-applied when the user switches providers.
inputsId	string | string[]	No	-	ID of one or more <Inputs> blocks. title and description resolve {{ .inputs.VarName }} expressions against them.

Usage

On successful authentication, the block sets these session environment variables, which later blocks inherit:

Provider	Variables
github	GITHUB_TOKEN, GITHUB_USER, GITHUB_HOST, GH_HOST (plus GH_ENTERPRISE_TOKEN on GitHub Enterprise Server)
gitlab	GITLAB_TOKEN, GITLAB_USER, GITLAB_HOST

GITLAB_HOST is the instance the token belongs to, either gitlab.com or your self-managed host.

A <GitClone> of a private github.com or gitlab.com repository uses the session GITHUB_TOKEN or GITLAB_TOKEN. To clone from a self-managed GitLab instance, set gitAuthId on the GitClone block so it uses the session GITLAB_TOKEN. Runbooks sends a session token only over HTTPS to the host it belongs to, never to another host or over plain http://, and not at all once a later script points GITHUB_HOST or GITLAB_HOST at a different host. For GitHub, GITHUB_HOST and GH_HOST record which host the token belongs to, so gh commands in later Command and Check scripts target the same host.

Explicit block references

Blocks can reference an auth block by ID so they wait for authentication and receive its credentials for that execution only:

• gitAuthId references a <GitAuth> block of either provider and injects the token and user it produced. Use this for GitLab.
• githubAuthId is GitHub only. It reads GITHUB_TOKEN and GITHUB_USER, so it cannot reference a GitLab block.

Caution

A GitLab <GitAuth> block cannot be referenced via githubAuthId. Use gitAuthId, or rely on the session environment, from which any <Command> or <Check> inherits GITLAB_TOKEN without an explicit reference.

Provider-locked aliases

Two aliases lock <GitAuth> to a single provider and hide the dropdown:

• <GitHubAuth> is equivalent to <GitAuth provider="github" hideProviderSelect />.
• <GitLabAuth> is equivalent to <GitAuth provider="gitlab" hideProviderSelect />.

Detailed example

The git-auth demo is a complete GitLab example.