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_hostslacks the GitHub entry. Runssh-keyscan github.com >> ~/.ssh/known_hostsagain.
Takeaways
- Deployments should depend on a machine's identity, not on a password a human types.
IdentitiesOnly yessaves hours of debugging on hosts with several SSH identities.
- 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
-
- Astro SSR with Podman: From Local Setup to VPS Astro with the Node standalone adapter in a two-stage Podman container, run locally with the same compose file that later goes to the VPS.
- Deploying Astro SSR to a VPS with Podman Moving the Astro SSR container to a fresh Debian VPS: Podman from the distro packages, a read-only deploy key and the same compose file.
- 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.
- Tags