gh

Log the GitHub CLI in on every workstation from one token Secret, without setting GH_TOKEN.

Install the GitHub CLI with the gh devtool and this toolconfig logs it in for you. Put your token in a Secret, then name it:

rl secret create gh-token -n local --from-string token=<your-token>
devtools:
  - name: gh
toolconfigs:
  - id: gh
    name: gh
    config:
      token: "${secret:gh-token/token}"

Inside the workstation, gh auth status reports you logged in, and gh pr, gh run and gh api work. A fine-grained token with read access to the repositories you need is enough for those; add pull-request write if you open PRs from the workstation.

That is the whole setup. The rest of this page covers GitHub Enterprise, pushing over SSH, the field list, and why this writes a file.

GitHub Enterprise

Set host:

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

Git pushes

By default gh tells git to use SSH for the repositories it clones, so pushes use a key you forward with an SSHKey and the token stays read-only. Set gitProtocol: https if you would rather git use the token too.

config fields

FieldTypeDefaultDescription
tokenstringrequiredThe OAuth token or personal access token, as a ${secret:NAME} or ${secret:NAME/key} reference. A missing token is an error.
hoststringgithub.comSet this for GitHub Enterprise.
gitProtocolstringsshssh or https: the protocol git uses for repositories gh clones.
userstringgithub-userThe login shown in gh auth status. The token decides the real identity; the label exists so the file is in the layout gh expects and gh does not rewrite it.

Why a file, and not GH_TOKEN

Ringleader writes gh’s own credentials file, ~/.config/gh/hosts.yml, owned by the login user and readable by nobody else. Setting GH_TOKEN in the environment would be shorter 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, leaving you in a mode you cannot change from inside the workstation.

Example

An opt-in layer that installs and logs in gh on every workstation you own. Create the Secret first; with an unresolved reference the workstation fails with a clear message.

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

Notes

  • 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 created for you: with no token there is nothing to log in with.