GitHub access for a coding agent on a server: deploy key, token or gh
What a deploy key, a fine-grained token and gh auth login let an agent on a server reach, how to set each up, and what their GitHub errors mean.
A coding agent on a server pushes and pulls with whatever GitHub credential its Linux user holds, and anything that can steer the agent can use that credential too. So choose by what it could do in the wrong hands. A deploy key reaches one repository, read-only unless you allow writes, and never expires. A fine-grained personal access token reaches the repositories and permissions you pick, under one owner, and can expire. gh auth login is the quickest, and the widest: its default token can read and write every repository your account can reach. For one repository, use a deploy key; for several, or when the agent also needs pull requests through gh, use a fine-grained token with an expiry.
The three, side by side
As GitHub documents them, as of November 2026:
| Deploy key | Fine-grained token | gh auth login (browser code) | |
|---|---|---|---|
Reaches | One repository | Repositories you select, all under one owner, plus read-only access to every public repository | Every repository your account can reach |
Can write | Only if you tick “Allow write access” | Only with the permissions you grant | Yes: the repo scope is full access to code |
GitHub’s API (issues, pull requests) | No, it is an SSH key for git | Within the permissions you grant | Yes, plus organisation membership and gists |
Expires | Never | On the date you set; no expiry is allowed unless an organisation forbids it | No date you choose; revoked by hand |
To revoke | Delete it from the repository’s Deploy keys | Delete it under Developer settings | Revoke the GitHub CLI app, which signs out every machine |
None of the three stops the agent from reading the credential itself. Claude Code, Codex, OpenCode and Pi all run git as your user, so whatever lets git push work lets cat print it. The agent does not have to turn hostile for that to matter: it only has to follow an instruction planted in a README, an issue or a dependency, which is prompt injection. What the credential can reach is the part you control.
A deploy key: one repository
GitHub’s deploy key docs define it as “an SSH key that grants access to a single repository.” Make the key on the server, so the private half never leaves it:
ssh-keygen -t ed25519 -f ~/.ssh/myrepo_deploy_key -C "agent server: myrepo"
cat ~/.ssh/myrepo_deploy_key.pub # the public half: this is what GitHub getsCopiedIn the repository on GitHub: Settings → Deploy keys → Add deploy key, paste the public key, and tick Allow write access only if the agent pushes. Write access is not a small step up: GitHub says a deploy key with it “can perform the same actions as an organization member with admin access”. A read-only key lets a misled agent read that one repository and nothing more.
Two of GitHub’s own cautions apply to an agent’s server in particular. Deploy keys “are usually not protected by a passphrase”, and an agent working unattended has nobody to type one; and they “don’t have an expiry date”, so a key on a server you stopped using still works until you delete it from the repository.
A key can be a deploy key on only one repository, so an agent working in three repositories needs three keys, and SSH needs to know which to offer. GitHub’s answer is a host alias per repository:
# ~/.ssh/config, one block per repository
Host github.com-myrepo
Hostname github.com
IdentityFile=/home/you/.ssh/myrepo_deploy_keyCopiedgit clone git@github.com-myrepo:OWNER/myrepo.git
# or, for a clone that already exists
git remote set-url origin git@github.com-myrepo:OWNER/myrepo.git
ssh -T git@github.com-myrepo # answers with OWNER/myrepo, not your usernameCopiedWrite the alias into the remote, as above, rather than telling the agent about it: an agent that clones with the plain git@github.com: address will be offered your default key, or none.
A fine-grained token: chosen repositories, chosen permissions
Create it on GitHub under Settings → Developer settings → Personal access tokens → Fine-grained tokens. Per GitHub’s token docs, it belongs to one resource owner (you, or one organisation), and under Repository access you pick Only select repositories. GitHub tells apps that git over HTTPS uses the Contents permission; for an agent that only reads, set it to read-only, and for one that pushes, read and write. Add Pull requests or Issues only if the agent is to open them through gh. Every token also gets “read-only access to all public repositories on GitHub”, which you cannot remove.
Set an expiry. GitHub allows a token with none unless an organisation’s policy forbids it, and a token that expires on its own is one fewer thing to remember when the server is retired. If the owner is an organisation that requires approval, the token stays pending and “will only be able to read public resources until it is approved”, which shows up as a push or a clone that is refused for no visible reason.
Avoid the classic token for this. GitHub says it “can access every repository that you can access”.
To put the token to use without it ever appearing on screen or in a shell history, save it into a file on the server with an editor (or copy the file over), then hand it to gh and let gh answer git’s requests for a password:
chmod 600 ~/github-token # the token, saved there by you; never echo it
gh auth login --with-token < ~/github-token
gh auth setup-git # git over HTTPS now asks gh for the token
rm ~/github-token
gh auth status # shows the account and where the token is keptCopiedThe gh auth login manual describes --with-token for classic tokens and warns that a fine-grained one there may cause “confusing behaviour” when gh reaches for resources outside its scope; it recommends the GH_TOKEN variable for fine-grained tokens instead. For git operations on the repositories you selected, the scoping is the point. Keep in mind too that GH_TOKEN, when set, “takes precedence over previously stored credentials”, so a GH_TOKEN left in a shell profile silently replaces the token you just logged in with.
On a server with no desktop keyring, gh keeps the token in a plain-text file in your home directory, as the guide to securing a VPS for Claude Code and Codex explains along with how to keep each agent away from the others’ credentials.
gh auth login: quick, and everything
Run with no terminal attached (the case when an agent runs it for you), gh auth login goes straight to GitHub’s device flow and waits. With GitHub CLI 2.45.0 on Ubuntu 24.04 it printed:
! First copy your one-time code: XXXX-XXXX
Open this URL to continue in your web browser: https://github.com/login/deviceCopiedYou open that address on your laptop or phone, enter the code, and approve. In a terminal of your own it asks a few questions first, among them whether to authenticate Git with your GitHub credentials. GitHub’s credential caching page says that with HTTPS chosen and that answered yes, “GitHub CLI will automatically store your Git credentials for you”. After the device flow, gh auth setup-git does the same for git.
The catch is the token that comes back. gh asks for the repo, read:org and gist scopes, and GitHub’s scope list says repo “Grants full access to public and private repositories including read and write access to code”. On an agent’s server that is every private repository you, and every organisation you belong to, let you reach. Recent releases of gh add an --expiring flag that asks for credentials it refreshes itself, which the manual calls “a preference, not a guarantee”.
Undoing it takes two steps. gh auth logout “does not revoke authentication tokens”; it only removes them from the machine. To kill the token, revoke the GitHub CLI application at github.com/settings/applications, which signs gh out everywhere, your laptop included.
If the agent genuinely needs broad access, GitHub’s documented shape is a machine user: a separate GitHub account that holds only the agent’s repositories, so gh auth login as that account reaches what you gave it and none of your own. For an organisation, GitHub recommends a GitHub App, whose installation tokens “expire after 1 hour”.
The messages, and what each one means
git@github.com: Permission denied (publickey).GitHub knew none of the keys SSH offered, or SSH offered none. With deploy keys, the usual cause is a remote that saysgit@github.com:instead of the repository’s alias.ssh -vT git@github.com-myrepolists the key files SSH tried, per GitHub’s troubleshooting page.- “fatal: could not read Username for 'https://github.com': No such device or address” The remote is HTTPS, git has no credential for it, and there is no terminal to ask you, which is how an agent’s shell runs. With
GIT_TERMINAL_PROMPT=0set, the end of the line reads “terminal prompts disabled” instead. Give git a credential helper (gh auth setup-git) or switch the remote to a deploy key’s SSH address. If the repository is public and the clone still fails this way from a cloud server, that is a different problem: the public-repository case has its own fix. - “Error: Key already in use” You tried to add a public key that is already attached somewhere: a deploy key on another repository, or your own account. GitHub’s page on it says that once a key is a deploy key on one repository, “it cannot be used on another repository”. Make a new key per repository.
ssh -T -ai ~/.ssh/KEYFILE git@github.comshows where a key is attached: a reply namingowner/repomeans it is a deploy key there. - “Permission to user/repo denied to user/other-repo” The key SSH offered is the deploy key of a different repository. On a server with a key per repository, the remote is most likely using the wrong alias, or none.
- “Permission to user/repo denied to other-user” The key or token belongs to an account that does not have access to the repository: a machine user nobody added as a collaborator, or a
ghlogin as the wrong account. - “The requested URL returned error: 403” or “Repository not found” over HTTPS. GitHub’s cloning errors page reads both as no access. With a fine-grained token, check that the repository is among the selected ones, that Contents allows writing if this was a push, and that an organisation’s approval is not still pending.
- “ERROR: The key you are authenticating with has been marked as read only.” Reported by users (one forum report dates from 2018) when pushing with a deploy key added without write access; GitHub’s docs do not quote it. Tick Allow write access, or decide the agent should not be pushing.
When the agent’s own sandbox is in the way
A push that works from your shell can fail from inside the agent. Codex runs commands with the network off by default, as the guide to Codex on a Linux server covers, so a git push it runs in its sandbox cannot reach GitHub whatever credential is set up; with approvals on, it offers to rerun the command outside the sandbox. And if you denied ~/.ssh or ~/.config/gh to the agent’s commands so it cannot read your credentials, its own git cannot read them either: ssh and the gh credential helper run as its commands do. One way through is to keep the agent’s deploy key in its own path outside the denied folders, and deny the rest. Simpler still is a separate Linux user per agent, holding only that agent’s keys, as the securing guide above sets out; the agent is then installed and signed in under that user, as in installing Claude Code on Linux.