Use a Pool in Workflows

To run a job on your pool, change its runs-on line. Nothing else in the workflow has to change.

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

The four labels are self-hosted, quant, the name of your pool, and the architecture (x64 or arm64). Each pool in the dashboard has a Copy runs-on line button for each of its architectures.

Choose the architecture

Use arm64 for images that run on ARM64 environments and x64 for images that run on x86_64 environments. A native build is much faster than a build under QEMU emulation.

To build for both architectures, run one job on each and join the results:

jobs:
  image:
    strategy:
      matrix:
        arch: [arm64, x64]
    runs-on: [self-hosted, quant, build, "${{ matrix.arch }}"]
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t "$IMAGE:$GITHUB_SHA-${{ matrix.arch }}" .

The pool must offer every architecture your jobs ask for. A job that asks for an architecture the pool does not have stays queued.

Install the tools a job needs

The runner image is lean. Add a setup action for each language a job uses:

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm test

Docker, Git, the GitHub CLI (gh), the AWS CLI, Node.js, jq, yq and zstd are already on the image.

Docker and service containers

Docker works without any setup. Service containers, container: jobs and Docker Compose behave as they do on GitHub-hosted runners.

Each job starts in a fresh container, so nothing a job writes to disk is there for the next job. Use actions/cache or a registry cache when you want to keep build layers or dependencies between jobs.

Cloud access without stored keys

GitHub’s OpenID Connect tokens work on Quant runners. A job with permissions: id-token: write can exchange its token for short-lived cloud credentials, for example with aws-actions/configure-aws-credentials, so you do not need to store a cloud access key as a secret.

Queueing

The tier sets how many jobs run at once. When all slots are busy, GitHub shows further jobs as queued, and they start as slots become free. Jobs are not dropped.

When a pool has been idle, its machines are stopped. The first job then waits about a minute for a machine to start. To avoid the wait during the working day, turn on Keep one VM warm in business hours for the pool.

Using Quant and GitHub-hosted runners together

You can move one job at a time. Jobs with runs-on: ubuntu-latest keep running on GitHub, and jobs with your pool’s labels run on Quant.

Workflows in public repositories must stay on GitHub-hosted runners.