GitHub Actions

Point a repository at your control plane and a queued workflow job gets a runner from the pool, started for that one job and gone afterwards.

What it actually does

falllow does not reimplement GitHub's runner protocol. It is proprietary, undocumented and a moving target, and reimplementing it would be an open-ended maintenance liability against something we do not control.

Instead a queued workflow job becomes an ordinary falllow job whose command starts the official actions/runner, registered just-in-time for that one job. GitHub talks to its own runner; falllow only decides which machine that runner appears on. Scheduling, leases, retries and resource limits are the machinery that already exists.

Registration is ephemeral by necessity. A persistent registration would bind a runner to one machine and destroy the pooling this exists to provide.

Connect a repository

In the manager, under GitHub, give the owner, the repository and an access token with the administration: write permission on it, that is the permission that lets falllow register a runner. The manager generates a webhook secret and shows it once.

Then add the webhook in the repository's settings. The secret is what proves a delivery came from GitHub; it is checked against that repository's own secret, so one repository's secret cannot forge events for another.

Repository → Settings → Webhooks

Payload URL    https://app.falllow.com/api/github/webhook
Content type   application/json
Secret         (the one the manager showed you)
Events         Workflow jobs

Ask for the pool

A workflow has to name every label the repository requires, self-hosted and falllow by default. Requiring only self-hosted would claim every self-hosted job in the repository, including ones meant for other runners.

.github/workflows/test.yml

jobs:
  test:
    runs-on: [self-hosted, falllow]
    steps:
      - uses: actions/checkout@v4
      - run: pytest -q

Add linux or windows to pin the job to one kind of machine. Without such a label the scheduler places it on anything eligible.

Pinning the OS

runs-on: [self-hosted, falllow, linux]

When nothing runs

A workflow job that no runner claims simply waits, which from GitHub's side looks like nothing at all. So every delivery whose signature verified is recorded with what the bridge decided about it, and the manager shows that list.

Outcome	Meaning
runner queued	A falllow job was created for it. The manager links the two, in both directions.
labels did not match	The workflow did not ask for everything this repository requires. The record names which labels were missing.
repository disabled	Connected but switched off.
registration refused	GitHub would not issue a registration, usually a token that expired or never had the right permission. GitHub's own message is kept.

A delivery with a bad signature is rejected and nothing is written down, so the list cannot be filled by anyone who merely knows the repository name.

What it costs a machine

A workflow job is one unit of work of unknown size, so the runner job reserves two threads and no memory limit, a starting point that leaves room on a shared machine. It is given two hours; past that it is stuck, and holding the reservation longer costs the pool more than the job is worth.

The runner clones the repository itself, exactly as it would on any self-hosted machine, so nothing is shipped from your working directory.