Get started
DocumentationOperations

Deploys

Source

Push-based. The box never talks to GitHub.

Why push and not pull

The organisation disables repository deploy keys, and the house posture is push-based anyway. So the source of truth on the box is a bare repository, and deploying means pushing to it.

bash
git remote add vps ssh://ubuntu@<host>/home/ubuntu/vitna-web.git
git push vps main

What the hook does

A post-receive hook checks main out, runs npm ci and the build, applies migrations, seeds, and restarts the service. Every deploy appends to a log on the box.

The order matters: it builds, migrates and seeds before it restarts anything, and aborts on the first failure with the previous build still serving.

Automatically

The deploy job runs on every push to main and needs both test jobs, so a red CI stops the deploy. It was its own workflow until it was folded in, which meant it raced CI rather than waiting for it.

The mirror workflows push with the default token, which never triggers other workflows, so each carries its own copy of the deploy step gated on whether a commit actually landed. A shared concurrency group keeps the two from pushing at once.

The credential is narrow

The Actions key is bound on the box to a forced command permitting exactly one operation, receive-pack on that one bare repository. No shell, no pty, no forwarding. The workflow pins the host key rather than trusting first use.

What the automatic check proves

Git ignores a post-receive exit code and the hook writes to a log file, so a failed build or migration reaches Actions as silence: the push itself succeeded.

The job reads the health endpoint afterwards and compares the revision it reports against the commit the job pushed. The hook records that revision into the environment file before it restarts, so it is the commit the running process was built from and not the one the bare repository points at. Those two disagree exactly when a deploy did not take, which is why a green deploy job is now the claim that your commit is serving, rather than only that something is.

A box whose hook predates that check reports no revision at all, and the job refuses rather than passing on a claim it cannot check. Install the current hook, which is a copy and not a link:

bash
cp /home/ubuntu/vitna-web/deploy/post-receive \
   /home/ubuntu/vitna-web.git/hooks/post-receive

A failed deploy rewinds the ref

The hook fires only when a ref moves, so a bare repository left pointing at a revision that never deployed makes the obvious retry a no-op: git answers Everything up-to-date, nothing is built or migrated, and the job goes green against the build that is still serving. The hook rewinds refs/heads/main on every failure, which is what makes pushing again mean what it appears to mean, and gives the ref an honest meaning: the revision that last deployed, rather than the one that was last received.

Read the log before retrying anyway. A push that appears to have done nothing has a reason, and the reason is on the box. Doing it by hand is written down in verifying a deploy.