GitHub

Installs gh (the GitHub CLI) and configures shell aliases and per-shell account selection.

Demo

What it does

• Auto-installs and updates gh to the latest GitHub release (release tarball on Linux, Homebrew on macOS)
• Bash tab completion for gh
• Keeps GitHub account selection per-shell (GH_CONFIG_DIR) so terminals never collide, see Per-shell isolation
• Shell aliases and functions for pull-request, issue, and workflow-run workflows

Aliases

Alias	Command	Description
github	gh-account	Show / switch the GitHub account
prl	gh pr list	List pull requests
prc	gh pr create	Create a pull request
prv	gh pr view	View a pull request
ghi	gh issue list	List issues
ghr	gh run list	List workflow runs

Functions

Function	Description
gh-authenticate	Select an account and run gh auth login in one step
gh-account	Show the current GitHub account, or switch to a named one

Authentication

The role installs the binary but leaves you signed out, so nothing writes credentials during an apply. Sign in once per account with gh-authenticate, which selects the account's GH_CONFIG_DIR and then runs the interactive gh auth login:

gh-authenticate personal                            # github.com
gh-authenticate work github.enterprise.example      # a GitHub Enterprise instance

The two steps it wraps — select, then log in — are also available on their own:

gh-account personal        # select the shell's account (a GH_CONFIG_DIR)
gh auth login              # sign in to github.com

For non-interactive hosts (CI, headless), export a token instead and gh reads it without a login step:

export GH_TOKEN=ghp_...

Multiple GitHub accounts and hosts

gh stores credentials in a single config dir (~/.config/gh), keyed per host in hosts.yml. That covers several different hosts at once out of the box: sign in to each and gh auto-selects the right one from the current repo's origin remote.

gh auth login                                    # github.com
gh auth login --hostname github.enterprise.example

What a single config dir cannot hold is two accounts on the same host (e.g. a personal and a work github.com identity) — one config keeps one token per host. gh-account solves that by giving each account its own config dir, scoped to the shell, and gh-authenticate selects one and logs in together:

gh-authenticate personal                         # ~/.config/gh/accounts/personal
gh-authenticate work github.enterprise.example   # ~/.config/gh/accounts/work, enterprise

gh-account <name> exports GH_CONFIG_DIR=~/.config/gh/accounts/<name>; run it with no argument to show the current account and list the ones you have. To override the host for a one-off command, gh still honours GH_HOST:

GH_HOST=github.enterprise.example gh issue list

Per-shell isolation

Account selection lives in the GH_CONFIG_DIR environment variable scoped to the current shell, never in a shared current account key. gh-account exports it rather than mutating one global config, so picking an account in one terminal cannot change which GitHub another terminal acts on.

Because selection is env-var driven, every terminal holds its own GitHub account. You can run several sessions at once, each signed in to a different account or host, including a coding agent like Claude Code, with no shared gh state for them to fight over. The starship prompt reads the same GH_CONFIG_DIR/GH_HOST and shows the account ( <account>), so each shell visibly shows the GitHub it is on. This is the per-shell context isolation concept applied to GitHub.