SYS.DOCS // DOCS

GitHub Actions Runners

GitHub Actions runners let workflow jobs run inside your Edka cluster instead of on GitHub-hosted runners. Edka installs and manages GitHub Actions Runner Controller (ARC), then creates private runner scale sets that are scoped to a GitHub repository or organization through your connected GitHub App.

Use private runners when CI jobs need access to cluster-local services, private network routes, custom node pools, larger machines, or Docker builds that you want to run inside your own infrastructure.

Requirements

A connected GitHub integration with access to the repositories that will use the runners.
An active cluster where you have write access.
Enough worker capacity for the minimum and maximum runner counts you plan to configure.
For Kubernetes container mode, a storage class if you want to override the default work volume storage.

Install the controller

Open a cluster and go to Actions.
Select Install controller.
Choose the GitHub integration this cluster should use to register private runners.
Confirm the install.

Edka installs the GitHub Actions Runner Controller add-on in the arc-systems namespace. This add-on is managed from Cluster > Actions, not from the generic Add-ons workflow, because the controller depends on the selected GitHub App installation.

The Actions overview shows the controller add-on status, configured scale sets, maximum runner capacity, and observed runner pods.

Create a runner scale set

Open Cluster > Actions > Scale Sets.
Select New or Add scale set.
Set Name / runs-on label. This is the default label you use in GitHub workflow jobs.
Optionally add extra runner labels, such as linux, gpu, or private-network.
Select a GitHub repository, or choose Custom GitHub URL for an organization or repository URL.
Set Min runners and Max runners.
Choose a runner namespace. The default is ci.
Choose the container mode and placement options.
Save the scale set.

Each scale set creates an ARC gha-runner-scale-set installation in the runner namespace. Edka also creates the required service account and GitHub App credential secret for that namespace.

Workflow usage

Copy the runs-on value shown in the Actions overview or Scale Sets view and use it in your workflow job.

jobs:
    build:
        runs-on: default
        steps:
            - uses: actions/checkout@v4
            - run: pnpm install && pnpm test

If you configure extra runner labels, use the label set shown by Edka:

jobs:
    build:
        runs-on: [linux, private-network]
        steps:
            - uses: actions/checkout@v4
            - run: pnpm test

Container modes

Docker-in-Docker

Docker-in-Docker is the default mode. It starts a runner container and, when enabled, a privileged Docker daemon sidecar so workflows can build container images with Docker.

Use this mode for workflows that need Docker commands such as docker build, docker run, or image publishing.

Kubernetes jobs

Kubernetes mode runs jobs through ARC’s Kubernetes container mode and uses a PVC for runner work storage.

Use this mode when workflows do not need a Docker daemon and you want job execution to fit more directly into Kubernetes scheduling and storage controls. Set Work PVC storage and, when needed, a storage class.

Placement and scaling

Min runners keeps warm runner capacity available for faster job starts.
Max runners caps the number of concurrent runners ARC can create for the scale set.
Node pool pins runner pods to a specific Edka node pool by adding the edka.io/nodepool selector.
Apply taint tolerations lets runners schedule onto a selected tainted node pool.

Dedicated node pools are useful for isolating CI workloads, using larger build nodes, or keeping privileged Docker-in-Docker jobs away from application workloads.

Runtime visibility

Use the Actions tabs to inspect and troubleshoot the runners:

Overview: controller status, scale set count, maximum runners, observed pods, and a workflow snippet.
Scale Sets: configured runs-on labels, scale windows, pod counts, CPU and memory usage, node pool placement, mode, and namespace.
Runners: live runner pod status and runtime details.
Logs: controller or runner pod logs with target, pod, container, tail, and follow controls.

Security notes

GitHub workflows can execute arbitrary commands from the repositories allowed to use a runner scale set. For production clusters:

Scope the GitHub integration to only the repositories that need private runners.
Avoid running untrusted pull request workflows on privileged Docker-in-Docker runners.
Prefer dedicated node pools for high-trust or resource-heavy CI workloads.
Keep runner namespaces separate from application namespaces when possible.