Runner controllers

Runner controllers enable admission control for CI/CD jobs routed through the job router. When a job is about to be executed, the job router sends an admission request to connected runner controllers, which can admit or reject the job based on custom policies.

Runner controllers are on the instance-level and are applicable to jobs depending on their scoping.

Use runner controllers to:

• Enforce custom admission policies like image allowlists, resource quotas, or security requirements.
• Control job queuing and resource allocation for capacity management.
• Ensure jobs meet organizational policies before execution for compliance enforcement.
• Limit job execution based on budget or resource constraints for cost control.

Admission control workflow

When you configure runner controllers with the job router, the admission control workflow operates as follows:

1. A runner controller connects to the job router.
2. The controller registers itself and starts handling admission requests.
3. When a job needs admission, the job router sends job details to connected controllers.
4. The controller evaluates the job against custom policies.
5. The controller sends an admission decision (admit or reject with reason).
6. The job router proceeds with job execution or reports the rejection.

View rejection reasons

When a runner controller rejects a job, the job fails with the job_router_failure failure reason. The job details page displays a message that includes:

• Job router information
• Runner controller information
• The rejection reason provided by the runner controller

Dry run mode logging

When a runner controller is in dry_run state, rejection decisions are not enforced but are logged as informational messages in the job router (KAS) backend logs. Use these logs to validate your controller’s behavior before you enable enforcement.

Runner controller states

Runner controllers can be in one of three states:

Scoping

Runner controllers must be scoped to be active. A runner controller without any scope does not receive admission requests, even when its state is enabled or dry_run.

Runner controllers support two mutually exclusive scoping types:

Additional scope types (group, project) are proposed in issue 586419.

To manage runner controller scoping, see the runner controllers API.

Manage runner controllers

Runner controllers are managed through the REST API. There is no UI for managing runner controllers yet.

• To create, list, update, or delete runner controllers, see the runner controllers API.
• To create, list, or delete scopes for runner controllers, see the runner controller scopes API.
• To manage authentication tokens for runner controllers, see the runner controller tokens API.

Prerequisites:

• You must have administrator access to the GitLab instance.

Implement a runner controller

For a step-by-step guide, see Tutorial: Build a runner admission controller.

To implement your own runner controller, you need to:

1. Create a runner controller in GitLab.
2. Scope the runner controller.
3. Obtain a runner controller token.
4. Connect to the job router with the token.
5. Register your controller with the job router.
6. Handle admission requests and send decisions.

For technical specifications and protobuf definitions, see the runner controller documentation in the GitLab Agent for Kubernetes repository.

Related topics

• Job Router
• Runner controllers API
• Runner controller scopes API
• Runner controller tokens API
• Tutorial: Build a runner admission controller
• Runner controller example (reference implementation)