How the Control Plane Works
Read this overview when evaluating whether the control plane fits your organization. Follow its links when you need deployment policy or implementation details. For installation steps, begin with Install and run safely.
Objectives
Section titled “Objectives”The control plane is designed to:
- operate enterprise-wide and organization-wide workflows from private central repositories;
- promote packages independently without coupling their release schedules;
- keep credentials and common policy centralized;
- separate repository selection from repository mutation;
- make every dispatched action attributable to a control-plane run;
- fail closed when routing, credentials, or worker eligibility are incomplete.
Mental Model
Section titled “Mental Model”
The execution boundary is the key architectural fact: orchestrators and workers run from the control repository. A worker checks out and analyzes one target at a time. Remote target repositories receive only declared safe outputs; they do not receive or run the control-plane workflow definitions.
Any repository may explicitly operate as a source-managed control plane for workflows it maintains in-tree. The reviewed workflow sources and generated locks are the runtime payload, while .github/workflows/cao.json remains the separate rollout-policy authority. When a catalog uses this topology to run its own workflows, it is dogfooding: the repository applies both catalog and control-plane safety rules. In every source-managed topology, repository visibility governs run metadata, dashboards, and review outputs, and source files alone never activate the control role.
How It Works
Section titled “How It Works”- A schedule or manual dispatch starts a package orchestrator in the control repository.
- Shared control resolves mode, routing, candidate repositories, limits, and eligible workers.
- The orchestrator ranks candidates and dispatches one worker run per selected target.
- Each worker analyzes only its dispatched target and emits only declared safe outputs.
- Outputs are sent to a review repository in review mode or processed against the target in live mode.
The orchestrator owns rollout and selection. Workers enforce the dispatched control envelope without escalating mode, discovering additional repositories, or duplicating credentials.
Core Safety Properties
Section titled “Core Safety Properties”- review mode is the default;
- target selection and dispatch are bounded;
- owners, targets, and review destinations must pass explicit trust checks;
- every live
(target repository, package)pair has one target-approved mutation authority; - workers accept only declared targets and eligible generated-workflow paths;
- GitHub tools are read-only, while writes use declared safe-output primitives;
- credentials are resolved inside each run and never carried in dispatch inputs;
- missing authority, authentication, routing, or eligibility fails closed.
Detailed References
Section titled “Detailed References”| Read | When you need to understand |
|---|---|
| Deployment and Governance | Organization and enterprise topologies, ownership, target enrollment, provenance, reporting identity, and the broader governance boundary |
| Execution and Safety | Layer responsibilities, the full execution flow, dispatch fields, invariants, failure behavior, and implemented controls |
| Orchestrators and Workers | Package-specific authority, worker enforcement, eligibility, and worker ceilings |
| Rollout and Routing | Review-to-live promotion; review destinations; authority checks; and rollback |