Push to deploy

A repository does not deploy by itself. Turn push to deploy on for one branch, and every push to that branch runs a build on the control plane and deploys the result to the project — the same thing runlot deploy does from your machine, started by git push.

runlot repo hook set app --branch main
# Every push to main in my-org/my-project/app will build and deploy to production,
# under your account. Continue? [y/N] y
# app: push-to-deploy is on.
#   branch     main
#   directory  the repository root
git push origin main

How a push becomes a deploy

1. You push to the hooked branch. Pushes to any other branch are ordinary pushes and start nothing.
2. The git server tells the control plane which commit the branch now points at. A build is queued. If a build for the same branch was still waiting in the queue, it is cancelled and replaced — three pushes in a minute produce one deploy, of the last commit.
3. The build runs: fetch the commit's tree, install dependencies, run the build script if there is one, then bundle and upload exactly as runlot deploy would.
4. On success the new version is live and the build links to it. On failure nothing changes — the previous deployment goes on serving — and the organization's admins get a build_failed notification.

Builds are serialized per organization: one at a time, in the order the pushes arrived. Two builds of the same project racing each other would decide which code serves by whichever finished first, and nobody chose that.

Turning it on

Setting the hook needs admin. Turning it on converts every future push, by anyone with write access, into a production deploy, and it does so under the account of whoever turned it on — that is a standing grant, which is why a deploy-scoped token cannot create one.

CLI

runlot repo hook set app --branch main               # turn on, or change the branch
runlot repo hook set app --branch main --root-dir apps/web
runlot repo hook status app                          # is it on, and for which branch
runlot repo hook disable app                         # off; the branch and directory are kept
runlot repo hook unset app                           # off, and the setting is removed
runlot repo deploy app                               # build the hooked branch's tip now, without pushing

runlot repo deploy is refused while the hook is off: a build has no directory to run in and no account to deploy as until someone has turned it on.

Dashboard

Open the repository and use the Builds tab. The card at the top states the current setting in one sentence — off, or "a push to main deploys" — with a button that changes it. Turning it on asks for the branch and, for a monorepo, the root directory. Turning it off asks you to confirm. The build history and the Deploy now button sit under it.

The branch rule

One branch, by name. Not a pattern, not a list. A pattern makes "why did my push not deploy" a question about glob semantics, and the answer to that question is never in the log.

The default offered is the repository's default branch. Changing the branch of a hook that is already on is not a new grant, so it does not move the account the deploys run under; only turning it on does.

The root directory

For a monorepo, name the subdirectory the build runs in — the one that holds the package.json and runlot.json of the app being deployed:

runlot repo hook set app --branch main --root-dir apps/web

It is a relative path inside the repository with no leading slash and no ... Empty is the repository root. The directory has to exist in the commit being built; a commit that removed it fails with clone_failed.

What the build environment contains

The build runs on the control plane, in a subprocess with its own scratch directory that is removed when the build ends. What it sees:

Migrations are not applied. A migration changes your data, and a git push should not perform that without anyone having asked. Run runlot pg migrate yourself, before or after the push, as your release order requires.

Build minutes

Build time is metered per organization and per calendar month, in wall-clock minutes of a build slot — a build that waits on a slow registry costs the same minutes as one that pegs a core.

The check runs when a build reaches the front of the queue. A build that finds the month's minutes used up fails with minutes_exhausted and nothing is deployed. The counter resets on the first of the month, UTC. The Builds tab and runlot builds both show how much of the month is used.

The log

Every build keeps its output — the package manager, your build script and the deploy step, interleaved with a marker line per stage. Read it in the Builds tab by opening the row, or with the CLI:

runlot builds                    # newest first, with the month's minutes under it
runlot builds show <buildId>
runlot builds log <buildId>      # the output, as it was written
runlot builds cancel <buildId>   # only while queued

The log is capped at 1 MiB, keeping the tail — the end of a failed build is where the error is. When the cap bites, the first line of the log says how many bytes were dropped. Logs are kept for as long as the project exists; there is no separate retention clock for builds.

When a build fails

The build's row carries a code, and the sentence explaining it is at the end of the log:

Two things hold on every failure. The previous deployment keeps serving: a build that did not produce a deployment touched nothing. And the organization's admins get a build_failed notification — in the dashboard, and by email for accounts with an address on file — at most once an hour per repository, so a push loop does not mail you eleven times but the second failure of a morning, the one that says your fix did not work, is not silent.

A build that is already running cannot be cancelled. It ends on its own inside the twenty minutes.

What it is not

• Not a CI system. There are no test steps, no matrices, no artifacts other than the deployment. A build is install → build → deploy, and the only thing it produces is a version.
• Not preview deployments. A push to any branch other than the hooked one does nothing. Preview addresses are runlot deploy --preview from your machine.
• Not a GitHub integration. The repository is one runlot hosts; see Repositories.