gh | Ringleader Docs

Authenticates the GitHub CLI inside the workstation by writing its credentials file (~/.config/gh/hosts.yml) from a Secret. Install gh with the gh devtool.

toolconfigs:
  - id: gh
    name: gh
    config:
      token: "${secret:gh-token/token}"

`config` fields

Field	Type	Default	Description
`token`	`string`	required	The OAuth token or personal access token. Write it as a `${secret:NAME}` or `${secret:NAME/key}` reference.
`user`	`string`	`github-user`	The GitHub login used as the account label. Cosmetic — the token determines the real identity — but it appears in `gh auth status`.
`host`	`string`	`github.com`	Set this for GitHub Enterprise.
`gitProtocol`	`string`	`ssh`	`ssh` or `https`; git’s protocol for `gh`-cloned repositories.

A missing token is an error, not a silent no-op — a credentials file with no token is a broken login.

Why a file, not an environment variable

Setting GH_TOKEN would be simpler and would break the workstation. An environment token takes precedence over stored credentials and disables gh auth login, gh auth logout, and gh auth switch — stranding you in a mode you cannot change from inside the workstation. Writing the credentials file instead leaves all of those working.

The file is owned by the login user at mode 0600.

Why `gitProtocol: ssh` by default

It keeps the two channels separate. A read-only token is plenty for gh pr, gh run, and gh api, while pushes ride SSH — using a key you forward with an SSHKey, not the token. Set https if you would rather git use the token too.

Example

An opt-in add-on layer. Create the token Secret first — with an unresolved reference the workstation fails loudly rather than writing a placeholder:

rl secret create gh-token -n local --from-string token=<your-token>

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: gh-cli
  namespace: local
spec:
  selector:
    matchLabels:
      owner: ada
  priority: 200
  devtools:
    - name: gh
  toolconfigs:
    - id: gh
      name: gh
      config:
        token: "${secret:gh-token/token}"
        user: ada
        gitProtocol: ssh

Then, inside the workstation:

gh auth status
gh pr list --repo acme/app

GitHub Enterprise

config:
  token: "${secret:ghe-token/token}"
  host: github.example.com

Notes

A fine-grained token scoped to the repositories you need is enough. Read access to metadata and contents covers most gh reads; add pull-request write to open PRs.
The token is resolved inside the workstation and never appears in the object, its status, or any diagnostic record.
Unlike claude-code and vscode-web, no gh toolconfig is ever synthesised for you: with no token there is nothing to authenticate.

config fields