Manual deploys work until the one time you forget, and then you spend twenty minutes wondering why the fix is not live. Once the update path on the VPS was solid, I let GitHub Actions trigger it on every push to main. This guide covers the wiring: a dedicated key, four repository secrets and an SSH step that runs the commands I used to type by hand.
The setup
- VPS: Debian, Podman, the project at
/opt/website, the container managed bypodman compose. - CI: GitHub Actions on
ubuntu-latestwithappleboy/[email protected]. - Model: pull-based. CI opens an SSH session and the server pulls from Git itself. Nothing goes from CI to the server except the signal to start.
The manual path has to work first
If podman compose misbehaves under my fingers, it will misbehave under CI as well:
cd /opt/website
git pull --ff-only origin main
podman compose -f compose.yml up -d --build
curl -I http://127.0.0.1:4321
If this is not stable yet, automate later. CI amplifies bugs, it does not hide them.
A dedicated deploy key
I generated a fresh ed25519 key pair for exactly this job. Reusing my personal key in CI would be asking for trouble.
ssh-keygen -t ed25519 -C "gha-vps-deploy" -f ./gha_vps_deploy_key -N ""
The two halves go to opposite sides:
gha_vps_deploy_key.pubinto~/.ssh/authorized_keysof the user on the VPS.gha_vps_deploy_key(the private key) into the GitHub repository secrets asVPS_SSH_KEY.
Use a dedicated deploy user with access to /opt/website and Podman: not root, not your personal login.
Repository secrets
Under Settings → Secrets and variables → Actions, four entries:
VPS_HOST: server IP or DNS name.VPS_PORT: usually22.VPS_USER: the deploy user.VPS_SSH_KEY: the content of the private key, over several lines.
The workflow
.github/workflows/deploy.yml:
name: Deploy VPS
on:
push:
branches: [main]
workflow_dispatch:
concurrency:
group: deploy-production
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy via SSH
uses: appleboy/[email protected]
with:
host: ${{ secrets.VPS_HOST }}
port: ${{ secrets.VPS_PORT }}
username: ${{ secrets.VPS_USER }}
key: ${{ secrets.VPS_SSH_KEY }}
script_stop: true
script: |
set -euo pipefail
cd /opt/website
git fetch --all --prune
git checkout main
git pull --ff-only origin main
if ! podman compose -f compose.yml up -d --build; then
podman rm -f website || true
podman compose -f compose.yml up -d --build
fi
podman ps --filter name=website
curl -fsS http://127.0.0.1:4321 >/dev/null
Two choices in it:
concurrencywithcancel-in-progress: false. A second push during a running deploy waits behind the first instead of killing it. A half-applied deploy is worse than a slightly delayed one.- The fallback. If the first attempt fails on a name conflict with a stale container,
podman rm -f websiteclears it and the second attempt goes through.
CI never holds registry credentials and never ships an image. It only tells the VPS to update itself.
script_stop only works with the pinned v1.2.0. The action removed it in v1.2.1, and the current release is v1.2.5 (as of November 2026). The set -euo pipefail at the top of the script does the same job, so drop script_stop when you update the action.1
First run
Run the workflow once by hand through workflow_dispatch before relying on the push trigger. Then check from the VPS:
curl -I http://127.0.0.1:4321
curl -I https://adrian-altner.de
sudo systemctl status caddy --no-pager
If the local and the public check both pass, the automatic deploy is live.
Common failures
Permission denied (publickey): the wrong private key inVPS_SSH_KEY, or the public key never reachedauthorized_keys. Check both halves.fatal: Not possible to fast-forward:mainon the server has diverged. Clean up or reset on the VPS; do not add--forceto the workflow as a shortcut.container name "website" is already in use: a stale container. The fallback in the script handles it.dial tcp 127.0.0.1:4321: connect: connection refused: the app container is down.podman logs websitesays why.
Takeaways
- For a single VPS, pull-based beats push-based: no registry credentials in CI, no image shipping, trust in one direction only.
- A dedicated key and a dedicated user keep the damage small if either leaks.
- Keep the script idempotent. The stale-container fallback costs four lines and removes a whole class of night-time alerts.
- 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.
- Builds on
-
- Updating the Website Repository on a VPS A repeatable update flow on the VPS: check the working tree, pull with --ff-only, rebuild with podman-compose, verify, roll back, all in one script.
- Uses
-
- Podman Container engine without a background daemon that runs rootless by default on Linux and uses the same commands on macOS and on a server.
- 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.
- My Old Astro Website My old site at adrian-altner.de: Astro with the Node adapter, typed content collections, IndieWeb features and photos as files with JSON sidecars.
- Tags