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 githubfails 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:
| 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:
- 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.
- Scope: choose Use as global default on my system, so
ghuses 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. - 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,logoutandrefreshstop 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 strayexport, can’t change whoghacts as. 1Password set it whenopstartsghdirectly (op run -- gh …) or whenDOT_OP_SHIM=ghcomes with it. Set that by hand whenop runstarts a script or a shell that then runsgh, sincegh’s parent isn’topthere:DOT_OP_SHIM=gh GH_TOKEN="op://<vault>/<item>/token" op run -- sh -c 'gh …' -
Messages go to stderr, so
gh … --jqoutput stays clean. -
Without the plugin (
op plugin init ghnot run), it runsghunchanged.
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.
-
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.
-
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
tokenand the tagdotfiles. -
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 -
Add the references to
dot.tomland apply.agent_tokenunder[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.