Cloudflare runners

Check compatibility

Cloudflare runners execute Linux x64 GitHub Actions jobs without a paired Mac. Use them for jobs that can run with shell commands, JavaScript actions, and composite actions. Your repository must be private, unarchived, and connected to the Mirage GitHub App.

• Docker commands, Docker container actions, service containers, and job containers are not supported.
• Pushes, manual workflow dispatches, and same-repository pull requests are supported. Fork pull requests are not admitted.
• Logs, artifacts, and job results stay in GitHub. The Actions cache is stored in Cloudflare R2.

Direct Cloudflare jobs use a separate runner label. They stay in the selected Cloudflare account and have no automatic fallback to a Mac or GitHub-hosted runner.

Choose a Cloudflare account

First connect GitHub, then select that account in Mirage and open Settings.

Use shared capacity

In the Cloudflare GitHub Actions execution section, select Shared. Shared capacity must be enabled for your account by a Mirage administrator, and the shared backend must be ready. If Mirage reports that shared access is unavailable, you cannot use this mode until access is enabled.

Use your own Cloudflare account

You need a Cloudflare account with Containers available and permission to create API tokens for that account. Mirage provisions and manages the runner resources there; their usage is billed to your Cloudflare account.

1. Find your Cloudflare account ID and create two API tokens scoped to that account.
2. Give the provisioning token access to manage Workers and their secrets and workers.dev route, Containers and the private registry, Workflows, D1, and R2 resources.
3. Limit the runtime token to the Containers and private registry operations needed to run jobs and build runner images.
4. In Set up or rotate a BYO backend, enter the account ID, Provisioning API token, and Runtime Containers token. Select Set up BYO.
5. Wait for the backend to become ready, then select BYO account.

See Cloudflare’s API token guide for token creation. Setup can take time while the runner image is built. If it fails, Settings shows the backend error; correct the credentials or account configuration and select Repair.

With either mode ready, turn on Cloudflare for the repository in Settings. The local-infrastructure switch is separate and is not required for a direct Cloudflare job.

Run a job

Create this workflow in the enabled repository and push it:

name: Mirage Cloudflare smoke test

on:
  push:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  smoke-test:
    runs-on: mirage-cloudflare-standard-3
    steps:
      - name: Check the runner
        run: |
          uname -s
          uname -m
          echo "Hello from Cloudflare"

Open the run in GitHub Actions and check the step output for Linux, x86_64, and Hello from Cloudflare. In Mirage, check that the job used Cloudflare. Then add your checkout, tool setup, dependency installation, and test steps.

You can also compare a completed Linux x64 job on Cloudflare. In that comparison flow, Cloudflare is currently available only for experiments and cannot be promoted to the default or automatic fallback. Direct Cloudflare workflows such as this example are supported separately.

Runner sizes

Select one profile for each job. These are Mirage’s preset labels:

mirage-cloudflare-ubuntu-latest is an alias for standard-3, not a promise of GitHub’s Ubuntu image contents. Account quotas may limit which sizes or how many concurrent jobs you can run.

For a custom size, use whole-number vCPU, memory in MiB, and disk in MB:

runs-on: mirage-cloudflare-vcpu:2-memory_mib:8192-disk_mb:16000

Custom sizes allow 1–4 vCPUs, at least 3,072 MiB memory per vCPU, and at most 12,288 MiB memory. Disk is capped at 20,000 MB and 2 GB per GiB of memory.

Manage your account

Settings shows the backend’s state, last error, health check, and cache usage. For your own account, use Repair to retry setup or Upgrade to update Mirage-managed runner resources. To rotate credentials, submit new tokens through the same setup form.

Changing the selected mode affects newly queued jobs; active jobs keep their original account. Before removing a BYO backend, change workflows that target it and select Drain to stop new work. Once active jobs finish, Remove deletes Mirage’s managed runner resources, including their D1 database and R2 buckets.