GitHub Actions runners

Coolify can run the GitHub Actions workflow jobs of a GitHub organization on your build servers. Each job runs in a new runner container. Coolify deletes the container after the job.

The runners run on your own servers, on self-hosted Coolify and on Coolify Cloud. Coolify never runs them on the server that runs Coolify itself.

How it works

1. A workflow job asks for runs-on: [self-hosted, <your label>].
2. GitHub sends a Workflow job webhook event to Coolify through your GitHub App.
3. Coolify finds an enabled build server whose labels match the job and that has free capacity. It selects the least busy server.
4. Coolify starts an ephemeral runner container on that server and registers it with GitHub.
5. The runner takes one job. When the job completes, Coolify deletes the container, its network, and its volumes.

When all runners are busy, the job waits in the Coolify queue until a runner is free. When a runner cannot start, Coolify removes it and tries again, up to 3 times. Refer to Monitor runners.

What you need

Before you start, make sure you have:

• a server with the Builds only role. Refer to Build servers.
• a GitHub App source in Coolify that belongs to a GitHub organization. Runners are registered at organization level, so GitHub Apps of personal accounts cannot run workflow jobs.
• a Coolify instance that GitHub can send webhook events to.
• outbound internet access from the build server to github.com, ghcr.io (runner image), and Docker Hub (Docker sidecar image).

Set up the GitHub App

The GitHub App needs these permissions and events:

Configure runners on a build server

You can configure runners on more than one build server. Coolify sends each job to the least busy server that matches the job labels.

Use the runners in a workflow

Add self-hosted and one of your custom labels to runs-on:

jobs:
  build:
    runs-on: [self-hosted, coolify]
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t my-app .

Coolify takes a job only when:

• the job asks for at least one of your custom labels, and
• all labels of the job are registered by the runner (self-hosted, linux, and your custom labels).

Jobs that ask only for generic labels, such as self-hosted, are left for other runners. This prevents Coolify from taking jobs that are for other self-hosted runners of your organization.

A custom label can contain letters, numbers, dots, dashes, and underscores. You cannot use self-hosted, linux, x64, arm64, arm, windows, or macos as the only label.

Docker in jobs

What works in each mode:

Coolify never shares the Docker socket of the host with a runner. Each runner has its own network and volumes.

Install Sysbox

When you select Isolated Docker (Sysbox), Coolify checks if the server has Sysbox. If Sysbox is not installed, select Install Sysbox. Coolify shows the installation logs.

The automatic installation needs:

• Debian or Ubuntu.
• The amd64 or arm64 architecture.
• Linux kernel 5.12 or newer.

During the installation, Coolify:

1. Writes the current bip and default-address-pools values of Docker to /etc/docker/daemon.json. It keeps the other settings and saves a backup of the file as /etc/docker/daemon.json.before-sysbox. Without these values, the Sysbox package restarts Docker, or stops when containers exist.
2. Downloads the pinned Sysbox package from GitHub and checks its SHA-256 checksum.
3. Installs the package and fuse3. Docker reloads its configuration. Running containers are not restarted.

For other distributions, install Sysbox manually. Coolify detects it when the Sysbox services run and Docker lists the sysbox-runc runtime.

Runner image

By default, Coolify uses ghcr.io/actions/actions-runner:latest and pulls it each time it starts a runner, so the runner stays up to date. When the registry is not available, Coolify uses the image that is already on the server.

In Runner image, you can:

• pin a version, for example ghcr.io/actions/actions-runner:2.337.0.
• use a custom image based on the official runner image, to add tools.

Monitor runners

The Recent runners section on the GitHub Runners page shows the queued jobs, the active runners, and their results. The list updates every 10 seconds.

When a runner cannot start, Coolify removes it and puts the job back in the queue. It tries again after 30 seconds, and then after 60 seconds, possibly on another build server. While it waits, the row shows Attempt 1 of 3 failed or Attempt 2 of 3 failed with the cause.

After the last failed attempt, the job stays queued on GitHub until GitHub cancels it. Another runner with matching labels can still take it.

To stop an active runner, select Cancel on its row.

Disable runners

Select Disable runners to stop taking new jobs. Coolify removes the runners that wait for a job. Running jobs continue until they finish. Coolify keeps the settings and the execution history of the server.

To take jobs again, select Enable runners.

You cannot change the role of a build server while its runners are enabled. Disable the runners first.

Troubleshooting