This is Phase 1 of the [Runner Job Router design document](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_job_router/), focused on the Admission Control use case. ## Problem Statement GitLab CI currently has no mechanism for organizations to enforce custom policies on jobs before they are assigned to runners, limiting control over what runs on their infrastructure and who can use specific runners. ## Proposal Introduce Runner Controllers as a programmable security layer that connects to GitLab Relay (previously KAS) via gRPC reverse tunnels and makes admit/deny decisions on CI jobs before runner assignment. Controllers are implemented by users in their preferred language using a standard gRPC interface, allowing organizations to encode their own policies. Multiple controllers can be configured at instance, group, and project levels, with jobs processed sequentially through all applicable controllers — all must pass. Example use cases: - **Admission control** — restrict who can use specific runners based on project, group, or user attributes - **Compliance enforcement** — apply organizational policies such as branch protection rules or approval requirements before jobs execute - **Cost and resource governance** — enforce quotas and prevent abuse on shared or expensive infrastructure This includes the Runner Controller management APIs, GitLab Relay integration, scoping, security and compliance controls, tooling, and documentation. ## Experiment Scope We are launching Runner Controllers as an **experiment** to get the core admission control capability into users' hands early. By observing how organizations adopt and apply custom job policies in practice, we will learn which policy patterns are most valuable, what data controllers need in admission requests, and how teams want to manage controllers at scale. These learnings will directly shape the [path to GA](https://gitlab.com/groups/gitlab-org/-/work_items/21239). The experiment delivers a fully functional admission control pipeline: - Runner Controller CRUD APIs (REST) and token management - gRPC reverse tunnel connectivity through GitLab Relay - Instance and runner-level controller scoping - Dry-run mode for safe testing and gradual rollout - Basic admission request payload (job and runner metadata) - Audit trail events for controllers and tokens - CLI (`glab`) and Terraform provider support - Initial documentation and example controller implementation - Integration tests and instrumentation/metrics ## Iterating towards GA Based on what we learn from experiment adoption, the [GA epic](https://gitlab.com/groups/gitlab-org/-/work_items/21239) will expand Runner Controllers with: - Organization, group, and project-level controller scoping for hierarchical policy enforcement - Full UI for controller management and monitoring - Enriched admission request payload informed by real-world controller usage patterns ## References - [Runner Job Router design document](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_job_router/) - [Runner Admission Controller blueprint](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_admission_controller/) - Follow-up: [Runner Controllers for admission and policy enforcement - GA](https://gitlab.com/groups/gitlab-org/-/work_items/21239)