Skip to content
dot
Esc
↑↓navigate↵open⌘Jpreview
On this page

GitHub

Connect the GitHub CLI to a token in 1Password, once per account and in a minute on each Mac.

gh, the GitHub CLI, needs a login to call GitHub’s API: creating repos, opening pull requests, adding SSH keys. git push and git pull don’t use it; they go over SSH with the key from 1Password (1Password and GitHub).

This guide uses the token in 1Password way. The interactive alternative is at the end, for comparison.

Requirements

1Password with Integrate with 1Password CLI turned on (1Password and GitHub, step 1).

1. Install the CLI

dot apply packages    # installs what's missing: here, gh

This installs gh and op, from config/packages.conf; what’s already installed stays as it is. op plugin init gh only works once gh exists.

2. Create a token (once, ever)

GitHub offers two kinds of personal access token. Pick one:

Kind Creating it Access
Fine-grained GitHub’s default; permissions picked one by one Only what you grant
Classic One pre-filled link, below Broad scopes

Both need GitHub’s 2FA when you create them. Either way, copy the token at the end: it’s shown only once, and the next step stores it.

Fine-grained (what GitHub offers by default)

Open https://github.com/settings/personal-access-tokens/new:

  • Name: gh CLI (1Password)

  • Expiration: your choice. A date means rotating the token when it expires (see Renewing).

  • Repository access: All repositories.

  • Repository permissions: set these to Read and write:

    • Administration (create repos)
    • Contents
    • Issues
    • Pull requests
    • Workflows

    Metadata becomes Read-only automatically.

  • Account permissions: set these to Read and write. Without them, dot apply github fails with HTTP 403:

    • Git SSH keys (upload your SSH key for authentication)
    • SSH signing keys (upload it for commit signing)

Picking permissions one by one is where most of the time goes.

Classic (fastest)

This link opens the form with the name and every scope already filled in; just pick an expiration and generate:

https://github.com/settings/tokens/new?description=gh%20CLI%20(1Password)&scopes=repo,read,workflow,gist,admin,admin

Scope Why
repo Work with your repositories, including private ones
read:org Read organizations; gh expects it
workflow Edit GitHub Actions workflows
gist Create gists
admin:public_key Add your SSH key for authentication
admin:ssh_signing_key Add your SSH key for commit signing

3. Connect it to gh (once per Mac)

op plugin init gh

It asks three things:

  1. Credential: choose Import into 1Password, paste the token, and save it in your built-in personal vault (Personal, or Private on business accounts). On a later Mac, choose the item that already exists instead.
  2. Scope: choose Use as global default on my system, so gh uses this token everywhere. It’s the third option: the list starts on Prompt me for each new terminal session, so move down before pressing Enter.
  3. It finishes by printing a command that adds a line to ~/.zshrc. Skip it: dot’s shim does that job for every process (step 4).

4. Use gh from anywhere (once per Mac)

dot apply shell

op shim gh (in config/shell.conf) links a shim to ~/.local/share/dotfiles/shims/gh, and config/shell/op.zsh puts that folder first on PATH. Every process that runs gh, whether your terminal, a script or an agent, finds the shim, which runs the real gh through op plugin run: the token goes into that one process. Open a new terminal so the PATH applies.

The line that op plugin init prints would load ~/.config/op/plugins.sh, whose gh function only exists in an interactive zsh. If you ran it, dot check shell names that line of ~/.zshrc; delete it.

What the shim does besides that:

  • gh auth login, logout and refresh stop with a message: the login lives in 1Password.

  • A token in the environment (GH_TOKEN, GITHUB_TOKEN) that 1Password didn’t set is ignored with a message, and the token from 1Password is used: a cloned repo’s .env, or a stray export, can’t change who gh acts as. 1Password set it when op starts gh directly (op run -- gh …) or when DOT_OP_SHIM=gh comes with it. Set that by hand when op run starts a script or a shell that then runs gh, since gh’s parent isn’t op there:

    DOT_OP_SHIM=gh GH_TOKEN="op://<vault>/<item>/token" op run -- sh -c 'gh …'
  • Messages go to stderr, so gh … --jq output stays clean.

  • Without the plugin (op plugin init gh not run), it runs gh unchanged.

Then add the dotfiles tag, keeping the one op added:

op item edit "GitHub Personal Access Token" --tags "1Password Shell Plugins,dotfiles"

5. Check it

gh auth status

It asks for Touch ID, then shows you logged in to github.com with the token from GH_TOKEN. That variable is set by the plugin for that single command; nothing is written to disk.

6. A token for agents (optional)

Your token can do everything you can, and an agent that goes through it asks for 1Password’s approval on every call, until approving becomes a reflex. An agent, or a script nobody watches, can get a token of its own instead: it reaches only the repos agents work on, and a 1Password service account fetches it without asking anyone. A fine-grained token belongs to a single owner, your account or one organization, so agents that work on repos of several owners get one token per owner.

  1. Create a fine-grained token at github.com/settings/personal-access-tokens: Only select repositories, with the repos agents work on. Repository permissions: Issues and Pull requests Read and write; Contents and Actions Read-only (Metadata comes with it). No Administration or Workflows. Contents stays read-only so an agent can’t merge: a token acts as you, admin included. Agents push branches over SSH, open pull requests, and you merge them. The Resource owner is the account or organization whose repos it reaches; repeat this step for each owner.

  2. In 1Password, create a vault named Agents that holds only agent tokens and nothing else: one API Credential per token (for example “GitHub Agent Token”), with the token in a field named token and the tag dotfiles.

  3. Create a service account with read access to the Agents vault and nothing else, and store its credential in your macOS keychain. The command asks for the value, so it never lands in your shell history or on disk in the clear:

    security add-generic-password -s dotfiles-op-agents -a "$USER" -w
  4. Add the references to dot.toml and apply. agent_token under [github] is for any owner without a token of its own; each line under [github.agent_tokens] is a GitHub user or organization and its token. Either can be left out:

    [github]
    agent_token = "op://Agents/GitHub Agent Token/token"
    
    [github.agent_tokens]
    example-org = "op://Agents/example-org Agent Token/token"
    dot apply shell

op agent-token gh $github.* keeps the reference in ~/.local/share/dotfiles/agent-tokens/gh, and dot check says when the keychain has no credential. From then on, the shim picks the token by who runs gh:

Who runs gh Token
You, in a terminal (stdin or stderr is one) yours, through the plugin, after 1Password’s approval
An agent (AI_AGENT, CLAUDECODE, CODEX_SANDBOX, CURSOR_AGENT or GEMINI_CLI set), even in a terminal the agent token, read by the service account: no prompt
A script without a terminal, launchd the agent token

With tokens under [github.agent_tokens], the owner the command targets picks the token. The first of these that applies gives the owner:

Owner from Example
-R or --repo gh pr list -R example-org/app
GH_REPO GH_REPO=example-org/app gh pr list
The repo right after a gh repo command, or a URL right after a gh pr or gh issue command gh repo clone example-org/app, gh pr view https://github.com/example-org/app/pull/1
The path of gh api gh api repos/example-org/app/pulls, gh api orgs/example-org
The current folder’s git remote, as gh picks it: the one gh repo set-default marked, then upstream, github, origin, then the owner all remotes share gh pr create in a clone

Owner names ignore case, and a remote on a host from ~/.ssh/config counts when that host is github.com. A command with no owner (gh api user, a folder that isn’t a repo, gh repo clone app without one) or whose owner has no token uses agent_token. Without agent_token, those commands fail. When a repo’s remotes belong to different owners, none of them is marked or named as above, and any of those owners has a token, the command fails and asks for -R or gh repo set-default: it never guesses between tokens.

An owner that uses your own token

Some organizations require an admin to approve fine-grained tokens. For an owner like that, agents can use your own token instead of an agent token:

[github.agent_tokens]
example-org = "personal"

A gh command aimed at that owner then runs as it does in your terminal: through the 1Password plugin, which asks for your approval on each call, even when an agent runs it without a terminal. If the approval doesn’t come (denied, timed out, nobody there), the command fails; it never falls back to an agent token. Other owners keep their agent tokens.

Your token isn’t limited to that owner: it reaches everything you can, and an agent can aim at any of it with -R. Your approval is the only guard, so read what each prompt is for, and expect one per call. dot check notes each owner set to personal.

What routing doesn’t do

Choosing a token is routing, not a boundary: an agent can pass -R to use any of them. Put only tokens you’d give any agent under [github.agent_tokens], and personal only where you’ll read each approval prompt; what each token can do is what you set when creating it on GitHub. A gh started by another gh (an extension) keeps its parent’s token.

Once an agent token exists, an agent never gets your token from any shim, except for an owner you set to personal, and then only with your approval: a CLI without an agent token of its own, such as vercel, fails for agents and works only from your terminal.

The service account’s credential goes only into op run, never into gh or what gh starts. If anything fails (no credential in the keychain, the service account or the item is gone), the command fails: it never falls back to agent_token, to your token or to an approval prompt. Run what needs your token, such as dot apply github or creating a repo, from your terminal.

This sets a safer default, not a wall. A process that runs as you can read the keychain item (security hands it over without asking) or reach your token through op plugin run. What a leaked credential reaches is what you gave it: the Agents vault, so the agent tokens, and through them the repos each one lists. If it leaks, revoke the service account and the token, and create new ones.

Friction

Criterion Token in 1Password Interactive login
Time ~10 min to create the token (fine-grained); per Mac: not measured not measured
Browser once, to create the token on every Mac
2FA once, when creating the token on every Mac, if asked
Per machine op plugin init gh (the shim comes from dot apply shell) the whole login
Expires as set when creating the token no
Secret on disk no in the macOS Keychain
Touch ID once per terminal session (each agent command is usually one) never

The token is created once; each later Mac repeats steps 1 and 3–5.

Renewing

If the token has an expiration date, GitHub emails you before it expires. Regenerate it on GitHub, then replace the value in the 1Password item. Every Mac picks up the new value on its next gh command.

Alternative: interactive login

gh auth login --hostname github.com --git-protocol ssh --web

It shows a one-time code and opens the browser, where you paste it and authorize. The token is stored in the macOS Keychain, and this has to be repeated on every Mac.

Was this page helpful?