Watch a ref

Rift builds a VM for a branch only when that branch is watched. Watching tells Rift to keep VMs warm at the branch's head and to rebuild them at every push; unwatching drains them. This page is how to see, add and remove watched refs, and what a warm count means.

Watch a branch

An admin of the organization that owns the repository, through an account Rift is enabled for, asks the agent:

rift_watch  github:acme/api  main
rift_watch  github:acme/api  main  warm=2

rift_watch takes repo, ref and an optional warm. The ref is a branch name; warm is how many VMs to keep parked at its head, one unless you say. Watching is idempotent: watching a branch that's already watched sets its count and leaves it watched.

The moment a ref is watched Rift asks GitHub for its head and starts warming: a machine boots, clones the repository at that commit, builds the system its Rift expression describes — or the base system, if there's none yet — and parks. The first VM at a commit is the slow one; a few minutes is normal.

See what's watched

rift_repos  acme-inc

Every repository of the organization, and for each watched ref its warm count, how many VMs are ready — parked at the head and waiting for a claim — and the head it's at, or head not known yet if Rift hasn't heard of a commit. When the last VM at the head failed to warm, it says so, with the reason the VM reported and how many times in a row Rift tried; Rift tries again after a while, or at the next push. The app's Repositories page shows the same, with ref head pending for a head Rift hasn't heard, and rift_whoami lists the watched refs too.

What a push does

Every push to a watched branch moves its head. VMs parked at the old head are drained — destroyed once nobody claims them — and new ones warm at the new head. A VM an agent already holds is not touched: a claimed VM never changes, whatever the branch does after it. The warm pools reference has the whole lifecycle.

Stop watching

An admin asks the agent:

rift_unwatch  github:acme/api  main

or, in the app, clicks Stop watching on the ref's row in Repositories. Unwatching drains the ref's warm VMs and stops future builds. VMs agents hold on that ref keep running until their tasks close; they just won't be replaced, and no new VM can be claimed on the ref. Watching it again starts warming again from the current head.