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_request, pull_request_target, merge_group, schedule, workflow_run, and delete workflows are supported. Fork pull-request runs are not admitted.
• Logs, artifacts, and job results stay in GitHub. Caching independently selects GitHub, Cloudflare R2, Machine or None. Machine uses configured R2 storage here.

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, open the repository in Repos and turn on Cloudflare in its Routing setting. 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 Cloudflare label for each job. Preset sizes range from mirage-cloudflare-lite (1/16 vCPU, 256 MiB memory) to mirage-cloudflare-standard-4 (4 vCPUs, 12,288 MiB memory), and a custom label can request an exact size. Runner labels lists every size and the rules for custom sizes.

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.