Triggering VPS Deploys with GitHub Actions

A GitHub Actions workflow that opens an SSH session to the VPS on every push to main and lets the server pull and rebuild itself.

Article Created Updated

Reviewed by adrian on

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 by podman compose.
  • CI: GitHub Actions on ubuntu-latest with appleboy/[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.pub into ~/.ssh/authorized_keys of the user on the VPS.
  • gha_vps_deploy_key (the private key) into the GitHub repository secrets as VPS_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: usually 22.
  • 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:

  • concurrency with cancel-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 website clears 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 in VPS_SSH_KEY, or the public key never reached authorized_keys. Check both halves.
  • fatal: Not possible to fast-forward: main on the server has diverged. Clean up or reset on the VPS; do not add --force to 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 website says 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.

Based on

  • Triggering VPS Deploys with GitHub Actions (raw/2026/2026-03-05/triggering-vps-deploys-with-github-actions.md) [post]
  • appleboy/ssh-action [ssh-action]

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.

Builds on

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.

Show in the graph view