vitna.ai/docs/operations/deploys Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/operations/deploys
> Raw Markdown: https://vitna.ai/docs/operations/deploys.md
> Corpus index: https://vitna.ai/llms.txt

# Deploys

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](verifying-a-deploy.md).
Human Machine Shift+M