Use this page to choose an outcome, confirm the responsible role, and either follow the current runbook or stop at an explicit product gate. It does not replace the linked runbooks.
- Current — implemented on the default branch and documented for the stated experimental scope.
- Prototype only — useful for isolated evaluation, not a managed or production path.
- In review — not available from the default branch; do not install it as current behavior.
- Planned — no supported command exists yet.
- Not production-ready — the repository does not authorize production use.
| Outcome | Status | Runs in | Changes state? | Current path or stopping condition |
|---|---|---|---|---|
| Install or converge an ordinary-CI worker/controller | Current, experimental | Prepared Linux Docker host, using reviewed private configuration | Yes | Follow the worker quickstart and desired-state lifecycle. |
| Add another worker host or location | Current, experimental | Private configuration, then the new Linux host | Yes | Follow adding a host; the application repositories do not change. |
| Authorize and onboard an application project | Current, experimental | Application repository, private configuration, and GitHub runner-group policy | Yes; no host mutation | Follow adding a project, then the migration procedure. |
| Create controller GitHub credentials and runner-group prerequisites | Current manual procedure; automation in review | GitHub web UI and the target host | Yes | Follow GitHub App setup and the runner-group procedure. Issue #27 and PR #75 track automated bootstrap and its required organization-owner evidence; do not use it from the default branch yet. |
| Run an isolated first-job proof | Prototype only | GitHub Actions and one isolated worker host | Yes, transiently | Follow the live pilot. Stop if the matching job queue is not proven empty. |
| Install a persistent test/staging environment host | In review | Separate test host | N/A on the default branch | Follow test-environment host; issue #23 and PR #76 track the installer and prepared-host evidence. Do not install it from the default branch yet. |
| Install a deployment host | Current core, experimental; activation separately authorized | Separate deployment host | Yes | Follow the deployer runbook. Issue #22 and PR #69 track the core implementation, whose merge uses local tests, required CI and review. Project migration and template adoption require reviewed adapters and separately authorized host preparation, credentials and activation. Core availability does not authorize deployment. |
| Deploy to production | Not production-ready | Separate production boundary | N/A | Stop. The project status and production evidence do not authorize this workflow. |
| Publish or update from the standalone configuration template | Published v1.0.0 release | Management workstation and a private configuration repository | Yes | Start from the public v1.0.0 release at reviewed template commit cf4a4d143540e0c70e1f301061038bbf95f04398. Its compatibility contract names reviewed ci-fleet core commit 0aed0d7e85e10050028b7d11fb12b84b3619e638. Follow that template commit's reviewed update procedure. Separately review and pin the engine commit for each deployment; v1.0.0 does not claim compatibility with current ci-fleet main. This partial correction is tracked by issue #24. |
| Role | Purpose | May hold | Must never hold or do |
|---|---|---|---|
| CI worker/controller | Run short ordinary-CI jobs in disposable runner containers | Narrow runner-registration identity and generic host state | Deployment credentials, production authority, project runtimes on the host, or untrusted public-PR jobs |
| Test/staging environment host | Keep an isolated deployed candidate available for integration or browser testing | Test-only credentials and disposable test data | Production credentials, production data, ordinary runner jobs, or production promotion |
| Deployment host | Apply an explicitly approved immutable artifact through application-owned deployment logic | Environment-specific deployment identity | Ordinary runner jobs, source builds for promotion, or another environment's credentials |
| Application project | Define its test image, task plan, and thin Actions workflow | Project code and project-scoped CI secrets | Fleet controller credentials, host inventory, or host-specific capacity |
| Private configuration repository | Declare reviewed pools, controllers, capacity, and required secret names | Secret-free logical desired state | Secret values, host addresses, project runtime code, or unreviewed engine refs |
A Linux machine must not combine the worker, tester, and deployer roles. Runner containers share a Docker daemon security boundary with their host; container separation does not make credentials on that host safe from a host-privileged job.
| Surface | Operator action | Mutates state? |
|---|---|---|
| GitHub web UI | Create/install the GitHub App, create the restricted runner group, review configuration changes, authorize a repository, dispatch the proof job | Yes |
| Management workstation | Prepare and validate secret-free desired state, open configuration/application pull requests, record immutable commit IDs | Yes when committed or pushed |
| Private configuration repository | Review runner pools, logical controllers, capacity, repository allowlists, lifecycle, and engine pins | Yes when merged |
| Application repository | Add the project-owned test image, task plan, CI entrypoint, and thin workflow | Yes when merged |
| Linux worker host | Place host-local identity files, run the installer, and verify cleanup/health | Yes for lifecycle operations; --check is read-only |
| Hypervisor or hosting control plane | Provision the isolated Linux machine, network, storage, and recovery boundary | Yes, but outside this repository; stop and hand off to its authorized operator |
Never put credentials, private host details, or real infrastructure inventory in this public repository or in secret-free desired state.
Prerequisites and credential placement are deliberate stopping points, not work hidden inside the installer. Complete the quickstart through reviewed configuration and host-local identity setup first.
Runs on: the prepared Linux worker host. Mutates state: yes (--install).
sudo ./scripts/install-worker-controller.sh --install --config-repo example-org/example-fleet-config --ref 1111111111111111111111111111111111111111 --controller example-ci-01Runs on: the Linux worker host. Mutates state: no (--check).
sudo ./scripts/install-worker-controller.sh --check --config-repo example-org/example-fleet-config --ref 1111111111111111111111111111111111111111 --controller example-ci-01The same script owns --adopt, --upgrade, --rollback, and --uninstall. Read the mode-specific prerequisites, stop conditions, expected report, and rollback behavior in desired-state lifecycle before using a mutating mode.
- The role is an ordinary-CI worker only; no tester, deployer, production, or unrelated workload shares the host.
- The engine ref is a reviewed full commit reachable from the public default branch.
- The desired-state ref is a reviewed merge commit from the private configuration repository.
- The configuration validates strictly and contains fictional/public-safe data only where examples are involved.
- Host-local credentials exist with the ownership and mode required by the runbook; no credential value appears in Git or command arguments.
- GitHub App installation, runner-group restriction, and the controlled-first-job queue condition are proven.
- The operator has an explicit host recovery or replacement boundary.
- Installer result is successful and records the intended controller, engine ref, and lifecycle state.
-
--checkreportsCHECK_OKagainst the same immutable inputs. - The controlled proof job uses read-only permissions and the expected shared routing label.
- The job is attributed to the intended scale set/controller.
- No ephemeral runner container or job-owned Docker resource remains.
- A fresh health evaluation succeeds and the controller returns to its configured idle state.
- Existing project CI remains enabled until parallel validation and rollback gates are complete.
If any item cannot be proven, stop without broadening permissions or improvising another role's installer.
Store this report in the operator's approved private record, never in a public issue when it would reveal infrastructure or repository inventory.
Operation:
Role:
Result: SUCCESS | STOPPED | FAILED
Engine commit:
Configuration commit:
Controller or logical target:
Installer mode:
Validation performed:
GitHub-side evidence:
Cleanup and health evidence:
Rollback or replacement point:
Warnings:
Next safe action:
The report records identifiers and outcomes, not credential values, tokens, private keys, addresses, or internal host details.
| Symptom | Check | Safe next action |
|---|---|---|
| Job remains queued | Complete runs-on expression, runner-group authorization, controller health, and scale-set identity |
Correct reviewed policy or labels; do not raise capacity blindly. |
| Installer cannot read private configuration | Credential visibility for the root-run installer and scheduled drift service | Provide the documented narrow read path; do not copy a repository-writing token onto the worker. |
| Health service looks inactive | It is a timer-driven oneshot, so stale systemctl status is not a fresh evaluation |
Start the health service explicitly, then run installer --check as documented in the quickstart. |
| Host is not clean after a job | Fleet ownership labels scoped to the runner/job, not global Docker state | Stop onboarding, preserve evidence, and use scoped cleanup only; never run global prune. |
| A guide asks for an unavailable role | Status table above | Stop at the linked issue or review gate; do not combine roles or invent a production path. |
For detailed errors and recovery commands, use the runbook linked from the selected outcome rather than reconstructing the workflow from this summary.
Follow managed images for runtime-source scalar semantics, producer evidence, protected warm proof and exact-ID recovery. Keep the existing Docker backend and capacity. Stage matching pending capability evidence before selection. Established image-free fleets first integrate any missing observed incumbent evidence, then target pending records, with fleet state unchanged in both preparatory commits. Preserve those records through manager staging and image introduction. For manual adoption, confirm that trusted complete incumbent source and exact original objects remain available. A candidate with a different revision cannot substitute its Compose or identity semantics for recovery. Preserve captured historical source paths for maintenance. Missing or untrusted source/proof requires controlled preparation or reviewed recovery before retrying. Obtain independent native classic/containerd evidence before host activation. Do not repair drift by editing rendered runtime IDs or replacing historical image catalogs.