GitHub Deploy Key on a VPS

A read-only SSH deploy key so a VPS can pull from GitHub without a personal access token or a password.

The first time I tried git pull on the VPS to ship an update, GitHub slammed the door:

Invalid username or token. Password authentication is not supported

Pasting a personal access token onto the server worked once but felt wrong. Tokens expire, end up in shell history and bind the deploy to a single human account. An SSH deploy key fixes all three. This is the setup I've used for every pull-based deploy since.

Create a dedicated SSH key on the VPS

A key that lives only on this VPS, labelled so I can recognise it in the GitHub interface later:

mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "vps-website" -f ~/.ssh/id_ed25519 -N ""
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
cat ~/.ssh/id_ed25519.pub

Ed25519 rather than RSA because the keys are shorter and faster, and GitHub has supported them for years. Copy the printed public key for the next step.

Add the key as a deploy key

In the repository on GitHub: Settings, Deploy keys, Add deploy key.

I keep it read-only unless the VPS actually needs to push, and for pull-based deploys it never does. A read-only deploy key is less dangerous than a personal access token: it's scoped to a single repository, can't be used to escalate elsewhere and doesn't expire.

Trust GitHub's host keys

Adding GitHub to known_hosts up front avoids the interactive "Are you sure?" prompt during the first git clone in a non-interactive deploy script:

ssh-keyscan github.com >> ~/.ssh/known_hosts
chmod 644 ~/.ssh/known_hosts

Test SSH access

ssh -T [email protected]

A friendly "Hi <repo>! You've successfully authenticated…" means the key is live. If it fails here, fix it before touching the repository's remote.

Switch the remote from HTTPS to SSH

cd /opt/website
git remote set-url origin [email protected]:adrian-altner/website.git
git remote -v
git fetch
git pull

From here on, deploys involve no interactive authentication at all.

Optional: an explicit SSH config

For hosts with several keys, or anywhere I want "use only this key for this host":

# ~/.ssh/config
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
chmod 600 ~/.ssh/config

IdentitiesOnly yes is the important line. Without it, ssh offers every key the agent knows before the right one, which is what usually causes "too many authentication failures" on machines with more than a couple of keys.

Quick troubleshooting

  • Permission denied (publickey): the key isn't attached to the right repository or account. Check the repository's deploy keys, not your personal SSH keys.
  • Repository not found: usually a typo in the remote URL, or the deploy key is attached to another repository than you think.
  • Host key verification failed: known_hosts lacks the GitHub entry. Run ssh-keyscan github.com >> ~/.ssh/known_hosts again.

Takeaways

  • Deployments should depend on a machine's identity, not on a password a human types.
  • IdentitiesOnly yes saves hours of debugging on hosts with several SSH identities.

More on this

Topic
  • Self-Hosting Running services on a server you control instead of using a provider's hosted version, with the upkeep that comes with it.
Mentioned in
See also
  • Mirroring GitHub to Codeberg A GitHub Actions workflow that mirrors branches and tags to Codeberg with plain git push over SSH, without a third-party action.

Show in the graph view →