Use this index to find ci-fleet concepts, requirements, examples, and step-by-step procedures. Repository Markdown is the authoritative documentation and is versioned with the implementation it describes.
New operator? Use Operator workflows to select a supported role and outcome or stop at an explicit product gate. For the current ordinary-CI path, follow the Quickstart: what ci-fleet does, install one controller, connect one repository, run and verify one job. Everything below is reference.
| I want to… | Read |
|---|---|
| Choose a host role and complete or safely stop an operator workflow | Operator workflows |
| Complete the beginner path end to end | Quickstart |
| Understand the whole system | Architecture |
| Understand how ephemeral runners are created | Runner controller design |
| Decide whether it fits my infrastructure | Architecture and the root README |
| Try the experimental implementation safely | Live pilot runbook |
| Add another Docker host, VM, computer, or VPS | Adding a host |
| Manage controller configuration from Git | Git-authored controller desired state |
| Create the controller GitHub App identity | GitHub App setup |
| Add a private project to the shared runner pool | Adding a project |
| Convert an existing GitHub Actions workflow | Migrating existing CI |
| Make a project compliant | Project CI standard and compliance checklist |
| Split tests across parallel workers | Project CI standard and the parallel workflow example |
| Configure automatic updates and cleanup | Host maintenance |
| Monitor hosts and detect missed reports | Fleet health monitoring and authenticated status reporting |
| Handle GitHub App, workflow, or deployment secrets | Secrets model and security policy |
| Review accepted implementation scope | Design decisions |
| Run private CI or deployment for a public project | Public projects, private delivery, and private configuration |
| Review current priorities | Roadmap |
| See what informed the design | Discovery summary |
| Term | Meaning |
|---|---|
| Fleet host | A generic Linux machine, VM, or VPS running Docker and a controller. It contains no project runtime. |
| Controller | Host-side service that watches GitHub demand and creates or removes ephemeral runners. |
| Ephemeral runner | A disposable GitHub Actions runner container that accepts one job and is destroyed. |
| Project test container | The project-owned Docker image containing its Node, PHP, Python, database, or other test environment. |
| Runner group | GitHub organization policy that controls which repositories may use a runner pool. |
| Scale set | One controller's uniquely named runner capacity advertised to GitHub. |
| Shared routing label | The stable runs-on capability used by compatible projects, regardless of which physical host accepts the job. |
| Test shard | One bounded slice of a larger test suite, designed to run independently and usually finish within five minutes. |
| Private delivery configuration | Repository allowlists, logical controllers, capacity budgets, environment policy, and required secret names kept in a private but secret-free repository. |
| Desired state | A reviewed schema-v3 declaration of runner pools and logical controllers stored in a private, secret-free Git repository. |
- System architecture
- Runner controller design
- Accepted design decisions
- Public projects, private delivery, and private configuration
- Secrets model
- Security policy
These pages are normative for compatible projects and hosts:
- Project CI standard
- Migration procedure
- Compliance checklist
- Host maintenance standard
- Fleet health monitoring
- Authenticated controller status reporting
- Status receiver deployment
- Git-authored controller desired state
- Secrets model
- Security policy
- Choose a role and outcome, then complete or safely stop the workflow
- Run the live pilot
- Add a host
- Install, adopt, check, upgrade, roll back, or remove a controller
- Add a project
- Deploy the current experimental prototype
- Maintain, drain, clean, update, and reboot hosts
- Use the public configuration-repository scaffold
The schema-v3 worker-controller installer is implemented as scripts/install-worker-controller.sh. Its accepted scope is isolated ordinary-CI fleet hosts under reviewed desired state; use the desired-state guide, pin both configuration and engine commits, and retain the manual pilot runbook for each host's isolated first-job proof.
- Read-only experimental workflow
- Private-repository live pilot
- Parallel five-minute job matrix
- Project task plan
- Standard project CI entrypoint
- Project test Dockerfile
- Isolated Docker Compose configuration
Examples use fictional values and are starting points. Pin reviewed actions and images before production use.
- Mandatory instructions live in this repository.
- Implementation changes update affected documentation in the same pull request.
- Real secrets, hostnames, internal addresses, and private repository inventories never appear in public examples.
- The GitHub Wiki is not an independent source of operational truth.
- A future generated documentation site may improve browsing, but repository Markdown remains its source.