Before anything: the access gate
A client reaches the operator pilot only after the account gate is satisfied — the client role, an active account, and an approved registration. Approving a registration and approving a repository scope are two different acts: the first lets a person in, the second lets a device take work.
Nothing here asks for a secret. The operator issues a single-use enrollment; the device redeems it and keeps only its own revocable bearer. A client secret or App private key is never sent to a person or a device.
Approve repository scope
Scope is a GitHub App installation, not a name on a list. Approving a scope means deciding which installation — and therefore which repositories — a device may serve:
- The App is installed on the client’s organization or repositories, for a private repository you have agreed to run.
- The installation ID is what partitions the control plane. A device enrolled for one installation cannot see or act on another’s work.
- An installation may cover several repositories; the worker serves the whole set and an assignment names one member of it.
Public repositories and outside-fork code are out of scope for this beta. Admission policy is not a hard pre-execution isolation boundary, so approve trusted private repositories only.
Issue a single-use enrollment
Enrollment is a one-time token that binds one device to one installation. Issue it, hand it over out of band, and let the device redeem it:
- The client runs the guided setup on the machine that will serve jobs.
- When setup asks, they redeem the enrollment via a hidden prompt or a protected local file — never a command argument or a shared note.
- The device stores a revocable, installation-bound bearer. If that device is lost, revoke the bearer; the tokens it could request are short-lived and requested by the broker, not held by the device.
Issuing an enrollment grants no repository access by itself. Scope comes from the installation; enrollment only lets this device take jobs for it.
Set the trigger policy
A client run is judged against a per-tenant policy before it is bound and again by the worker before it executes. The policy is four lists:
| Field | What it admits |
|---|---|
workflows[] | Workflow file names allowed to run on the device. |
events[] | GitHub events that may trigger an admitted run. |
branches[] | Branch patterns; a run on any other branch is refused. |
conclusions[] | Which outcomes are treated as admitted for the tenant. |
An absent policy keeps the original pilot contract, so an existing installation is not re-scoped by accident. A tenant can also publish the verifier steps it wants through a manifest; an unknown step is a validation error and never a dynamic dispatch.
Read the console
The pilot console shows the tenant’s own state. The two numbers that matter are reported separately, because they answer different questions:
- Queue — how many requests are waiting for a device, against the admission limit.
- Running — how many requests are claimed or executing, against the lease limit. A full running count with an empty queue is healthy; the reverse means devices are offline.
Requests carry a lifecycle you can follow to a terminal state, and a request sent to attention needs recovery. See recovery for what may safely return to the queue and what is non-retryable.