GuidesSecurity

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.

November 17, 2026The Everpod team
The short answer

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 keyFine-grained tokengh auth login (browser code)
Reaches
One repositoryRepositories you select, all under one owner, plus read-only access to every public repositoryEvery repository your account can reach
Can write
Only if you tick “Allow write access”Only with the permissions you grantYes: the repo scope is full access to code
GitHub’s API (issues, pull requests)
No, it is an SSH key for gitWithin the permissions you grantYes, plus organisation membership and gists
Expires
NeverOn the date you set; no expiry is allowed unless an organisation forbids itNo date you choose; revoked by hand
To revoke
Delete it from the repository’s Deploy keysDelete it under Developer settingsRevoke 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 gets
Copied

In 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_key
Copied
git 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 username
Copied

Write 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 kept
Copied

The 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/device
Copied

You 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

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.

Run Claude Code, Codex, OpenCode, Pi, Hermes or OpenClaw on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.