# Cloudflare runners

Run Linux x64 jobs without pairing a Mac, using shared capacity or your own Cloudflare account.

## 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](https://mirageci.com/docs/caching.md) 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](https://mirageci.com/docs/connect-github.md), then select that account in Mirage and open
[Settings](https://mirageci.com/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](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) 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](https://mirageci.com/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:

.github/workflows/mirage-cloudflare-smoke.yml:

```yaml
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](https://mirageci.com/docs/ci-providers.md) 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](https://mirageci.com/docs/runner-labels.md#cloudflare-sizes)
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.