DOCSEARCHbyAlgolia
Submit Docs

Actions Runner Controller (ARC)

repository·master·Indexed 27 days ago

https://github.com/actions/actions-runner-controller

A Kubernetes operator that automates the orchestration and scaling of self-hosted GitHub Actions runners using ephemeral, containerized runner scale sets. It includes support for Autoscaling Runner Scale Sets mode, which features scale-to-zero capabilities and reduced API pressure. The project provides a Helm chart for configuring authentication (GitHub App, PAT, or Basic Auth), Prometheus monitoring, webhook servers, and metrics servers.

Tokens
39.8K
Snippets
76
Records
189
Agent score
92%

What's inside actions-runner-controller

  1. Overview of Actions Runner Controller (ARC)

    master

    Actions Runner Controller (ARC) is a Kubernetes operator designed to orchestrate and scale self-hosted runners for GitHub Actions.

    It enables the creation of runner scale sets that automatically scale based on the number of workflows running in a repository, organization, or enterprise. Because these runners are ephemeral and container-based, they can scale up or down rapidly and cleanly.

    Note on Scaling Modes: The modern way to use ARC is via autoscaling runner scale sets. Previous autoscaling modes are now considered legacy and are maintained by the community only.

  2. Production readiness of RunnerSet

    master

    As of v0.22.0, RunnerSet is considered more production-ready. ARC has refactored its management logic to be shared between RunnerDeployment (Pod-based) and RunnerSet (StatefulSet-based).

    RunnerSet remains more customizable than RunnerDeployment and supports Persistent Volume Claims (PVCs), but it now benefits from the same generalized, reliable pod management logic used by RunnerDeployment.

  3. Monitor workflow jobs with actions-metrics-server

    master

    The actions-metrics-server is a component that exposes a GitHub webhook endpoint for receiving workflow_job events and collecting metrics related to jobs.

    Note: Currently, actions-metrics-server uses an in-memory state store to track workflow_job events (e.g., matching status=queued with status=in_progress to calculate queue duration). Because of this in-memory requirement, it cannot currently be scaled to 2 or more replicas.

  4. Ephemeral Runner behavior and API optimization

    master

    ARC v0.22.0 optimizes ephemeral runner management to reduce GitHub Actions RemoveRunner API calls:

    1. All runners managed by ARC now use the --ephemeral flag by default.
    2. ARC no longer makes unnecessary RemoveRunner API calls for ephemeral runners that have already completed their execution, aligning with GitHub's design where ephemeral runners are automatically unregistered after their first job.

  5. Understand the Autoscaling Runner Scale Sets mode architecture

    master

    The Autoscaling Runner Scale Sets mode provides a reliable and secure way to scale GitHub Actions runners. Key architectural features include:

    • No cert-manager requirement: Unlike previous modes, cert-manager is no longer a prerequisite.
    • Scale-to-zero: Supports scaling down to zero runner pods when no jobs are active.
    • Reduced API pressure: Minimizes requests to api.github.com to avoid rate-limiting.
    • Enhanced Security: GitHub Personal Access Tokens (PAT) or GitHub App installation tokens are no longer passed directly to the runner pod for registration.
    • Customizable Templates: Provides maximum flexibility for customizing runner pod templates.

    Workflow Lifecycle:

    1. The AutoScalingRunnerSet controller fetches the runner group ID via GitHub APIs.
    2. A Runner ScaleSet Listener pod establishes a long-poll HTTPS connection to the Actions Service.
    3. Upon receiving a Job Available message, the listener patches the EphemeralRunner Set resource to increase replicas.
    4. The EphemeralRunner Controller creates runner pods using a JIT (Just-In-Time) configuration token.
    5. Runners register with the Actions Service using the JIT token and execute the job.
    6. Once the job completes, the EphemeralRunner Controller manages the deletion of the runner pod.

  6. Understand the semantics of the `minRunners` field

    master

    In the current implementation of the AutoscalingRunnerSet, the minRunners field represents the minimum number of idle runners to maintain in the cluster.

    Instead of treating minRunners as the total number of runners (busy + idle), the controller now calculates the total desired runners as follows:

    1. Total Runners = (Number of assigned jobs) + (minRunners)
    2. If maxRunners is set: The desired number of runners is the lesser of maxRunners and the sum of (minRunners + number of jobs).

    This change ensures that even during job spikes or cold starts, there is always a buffer of idle runners available to decrease startup latency for incoming workflows.

  7. Service account roles in Actions Runner Controller

    master

    A working AutoscalingRunnerSet setup involves three distinct service accounts with different permission levels:

    1. Ephemeral runner Pod service account: Designed with the lowest privilege. In containerMode=kubernetes, it receives specific write permissions via a RoleBinding limited to a single namespace.
    2. AutoScalingListener Pod service account: Has a RoleBinding to a single namespace with a Role allowing PATCH permissions on EphemeralRunnerSet and EphemeralRunner.
    3. Controller manager service account: By default, this is a singleton with a ClusterRoleBinding providing broad permissions across the cluster to manage CRDs and resources like Pods, Secrets, Roles, and ServiceAccounts.

  8. Scalability improvements via GitHub API Caching

    master

    Starting with v0.22.0, ARC caches GitHub API responses (such as List Runners and List Workflow Jobs) based on the Cache-Control headers provided by GitHub.

    This significantly improves scalability because the number of API calls now scales proportional to the number of runner scopes (repositories, organizations, or enterprises) rather than the total number of managed runners. This allows ARC to scale to hundreds of runners more efficiently.

  10. Deploy ARC without cert-manager using custom certificates

    master

    If you are not using cert-manager, you can provide your own TLS certificates for the ARC webhook. Ensure your certificates include the following Subject Alternative Names (SANs):

    • actions-runner-controller-webhook.actions-runner-system.svc
    • actions-runner-controller-webhook.actions-runner-system.svc.cluster.local

    Steps:

    1. Create a TLS secret named actions-runner-controller-serving-cert in the actions-runner-system namespace.
    2. Pass the caBundle (base64 encoded) and set certManagerEnabled=false in your Helm configuration.
    $ kubectl create secret tls actions-runner-controller-serving-cert \
  -n actions-runner-system \
  --cert=path/to/cert/file \
  --key=path/to/key/file

$ CA_BUNDLE=$(cat path/to/ca.pem | base64)
$ helm upgrade --install actions-runner-controller/actions-runner-controller \
  certManagerEnabled=false \
  admissionWebHooks.caBundle=${CA_BUNDLE}

  11. Requirements for custom runner images

    master

    If you are bringing your own custom runner images to use with ARC, your image must adhere to the following contract:

    • The runner binary must be located under /actions-runner (specifically, /actions-runner/run.sh must exist).
    • The WORKDIR must be set to /actions-runner.
    • If the container user is root, you must set the environment variable RUNNER_ALLOW_RUNASROOT to 1.

    Note: Existing ARC runner images designed for older modes may not work out-of-the-box with the new ARC mode because they may place the binary under /runner or require specific configuration tokens/URLs passed at runtime.