# Runner Labels

Runner configuration can be expressed as labels directly in your workflow's `runs-on` field. You can configure Namespace runners through labels, so the entire configuration lives in your workflow as version-controlled code. This page walks through the label grammar and how to configure each feature directly with labels.

## Runner label grammar

### Machine label

The most important label is the one selecting architecture, operating system, and machine shape.

The label looks like `nscloud-{os}-{arch}-{shape}`

**Note:** only one `nscloud` label is allowed in the `runs-on` field of your workflow file. Namespace will not schedule any workflow job if `runs-on` specifies more than one `nscloud` label or invalid ones.

**Supported machine labels per OS**

| | Ubuntu | Windows | macOS |
| - | - | - | - |
| **OS** | `ubuntu-20.04` `ubuntu-22.04` `ubuntu-24.04` `ubuntu-26.04` | `windows-2022` | `macos-sonoma` `macos-sequoia-stable` `macos-sequoia` `macos-tahoe` `macos-tahoe-latest` `macos-tahoe-slim` `macos-tahoe-slim-latest` |
| **Arch** | `amd64` `arm64` | `amd64` | `arm64` |
| **Shape**These are our standard shapes. Larger and odd-sized shapes are available; see [Machine Shapes](/content/docs/architecture/compute/machine-shapes.md). | `2x4` `4x8` `8x16` `16x32` `32x64` | `2x4` `4x8` `8x16` `16x32` `32x64` | `6x14` `12x28` `12x56` |

Examples:

| Label | OS | Architecture | vCPU | Memory |
| - | - | - | - | - |
| `nscloud-ubuntu-22.04` | Ubuntu 22.04 | AMD 64-bit | 4 vCPU | 16 GB |
| `nscloud-ubuntu-22.04-amd64` | Ubuntu 22.04 | AMD 64-bit | 4 vCPU | 16 GB |
| `nscloud-ubuntu-26.04-amd64-4x8` | Ubuntu 26.04 | AMD 64-bit | 4 vCPU | 8 GB |
| `nscloud-ubuntu-24.04-amd64-4x8` | Ubuntu 24.04 | AMD 64-bit | 4 vCPU | 8 GB |
| `nscloud-ubuntu-22.04-amd64-4x8` | Ubuntu 22.04 | AMD 64-bit | 4 vCPU | 8 GB |
| `nscloud-ubuntu-20.04-amd64-4x8` | Ubuntu 20.04 | AMD 64-bit | 4 vCPU | 8 GB |
| | | | | |
| `nscloud-ubuntu-22.04-arm64` | Ubuntu 22.04 | ARM 64-bit | 4 vCPU | 8 GB |
| `nscloud-ubuntu-26.04-arm64-4x8` | Ubuntu 26.04 | ARM 64-bit | 4 vCPU | 8 GB |
| `nscloud-ubuntu-24.04-arm64-4x8` | Ubuntu 24.04 | ARM 64-bit | 4 vCPU | 8 GB |
| `nscloud-ubuntu-22.04-arm64-4x8` | Ubuntu 22.04 | ARM 64-bit | 4 vCPU | 8 GB |
| `nscloud-ubuntu-20.04-arm64-4x8` | Ubuntu 20.04 | ARM 64-bit | 4 vCPU | 8 GB |
| | | | | |
| `nscloud-windows-2022-amd64-4x8` | Windows Server 2022 | AMD 64-bit | 4 vCPU | 8 GB |
| `nscloud-windows-2022-amd64-8x16` | Windows Server 2022 | AMD 64-bit | 8 vCPU | 16 GB |
| | | | | |
| `nscloud-macos-sonoma-arm64-6x14` | macOS Sonoma | ARM 64-bit | 6 vCPU | 14 GB |
| `nscloud-macos-sequoia-arm64-6x14` | macOS Sequoia | ARM 64-bit | 6 vCPU | 14 GB |
| `nscloud-macos-tahoe-arm64-6x14` | macOS Tahoe | ARM 64-bit | 6 vCPU | 14 GB |
| `nscloud-macos-goldengate-arm64-6x14` | macOS Golden Gate | ARM 64-bit | 6 vCPU | 14 GB |

### Machine label suffixes

A machine label can be extended with one or more `-with-*` suffixes to enable extra capabilities on the runner, without changing its shape:

`nscloud-{os}-{arch}-{shape}[-with-cache][-with-features][-with-builders]`

For example, `nscloud-ubuntu-24.04-arm64-32x64-with-cache` selects an Ubuntu 24.04, arm64, 32x64 machine with a cache volume attached. Suffixes can also be chained to combine capabilities on a single runner, as shown below.

| Suffix | Effect |
| - | - |
| `-with-cache` | Attach a [cache volume](/content/docs/solutions/github-actions/caching.md#using-a-cache-volume/index.html) to the runner. |
| `-with-features` | Enable the settings passed in the [namespace-features:](/content/docs/solutions/github-actions/runner-controls.md) label. |
| `-with-builders` | Apply [Remote Builder](#remote-builders) configuration such as `nscloud-no-remote-builders` or `nscloud-in-runner-builder`. |

#### Combining cache and features

To request more than one capability on a single runner, chain the suffixes on the machine label. Order does not matter, and any companion labels are listed as separate entries. For example, a runner that has a cache volume and also runs privileged:

```yaml theme={null}
runs-on:
  - nscloud-ubuntu-22.04-amd64-8x16-with-cache-with-features
  - nscloud-cache-tag-my-repo
  - namespace-features:container.privileged=true
```

Here `-with-cache` attaches the cache volume (sized and tagged by the `nscloud-cache-*` companion labels) and `-with-features` enables the settings passed in the `namespace-features:` label.

## Attaching a cache volume

See [Cache Volumes](/content/docs/solutions/github-actions/caching.md) for the full caching overview.

Attach and configure the cache volume directly with runner labels. Use the following required labels:

* Append `-with-cache` to your [machine label](#machine-label), for example: `nscloud-ubuntu-22.04-amd64-8x16-with-cache`
* `nscloud-cache-tag-{tag}`, where tag is the key to select the volume to mount. Namespace attaches the most recently used volume with this tag. Valid tags may contain lowercase letters, numbers, `-` and `.` characters (`[a-z0-9.-]+`).

Setting these labels makes the cache volume available to the runner at path `/cache`. This location is static and not configurable at the moment.

By default the cache volume is 20 GB. To configure a custom size, specify `nscloud-cache-size-{size}gb`. The maximum size depends on your subscription plan: the Team plan includes 50 GB, and the Business plan offers 100 GB.

If you run GitHub jobs in a container, you also need to mount the cache volume inside the container. See [Running jobs in Containers](/content/docs/solutions/github-actions/runner-controls/containerized-jobs.md).

### Example: caching NPM packages

Use `nscloud-cache-action` to mount the volume under the paths you want to cache.

```yaml {4-6,9-15} theme={null}
jobs:
  tests:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-8x16-with-cache
      - nscloud-cache-size-20gb
      - nscloud-cache-tag-my-repository-e2e-tests

steps:
      - name: Setup pnpm
        uses: pnpm/action-setup@v4

- name: Setup PNPM cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          cache: pnpm

- name: Install dependencies and run tests
        run: |
          pnpm install
          pnpm run test
```

## Sharing a cache volume

Add the `nscloud-cache-tag-{tag}` label. Jobs carrying the same tag label share one cache volume, even if their machine labels differ:

```yaml {5,13} theme={null}
jobs:
  build:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-8x16-with-cache
      - nscloud-cache-tag-my-shared-cache

steps:
      - run: pnpm install

tests:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-4x8-with-cache
      - nscloud-cache-tag-my-shared-cache

steps:
      - run: pnpm run test
```

Both jobs attach the `my-shared-cache` volume, and so does any job in another repository that uses the same `nscloud-cache-tag-my-shared-cache` label.

## Container image caching

See [Container Images](/content/docs/solutions/github-actions/caching/container-images.md) for the full feature overview.

Configure the cache volume with the [required set of labels](#attaching-a-cache-volume), then add the label `nscloud-container-image-cache`.

For example, the following workflow definition asks for a cache volume of 50 GB with tag `e2e-tests`. Then, it lets Namespace automatically use it to cache the Docker ubuntu image.

```yaml {7} theme={null}
jobs:
  tests:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-8x16-with-cache
      - nscloud-cache-tag-e2e-tests
      - nscloud-cache-size-50gb
      - nscloud-container-image-cache

steps:
      - name: Pull ubuntu image
        run: |
          time docker pull ubuntu
```

The second time the above example runs, the time to pull the ubuntu container image should be close to 0, as every layer was already cached by the first run.

## Git checkout caching

See [Git Checkouts](/content/docs/solutions/github-actions/caching/git-checkouts.md) for the full feature overview.

Add the runner label `nscloud-git-mirror-{size}gb`, where `{size}` is an integer that indicates how large the cache volume storing the git mirrors should be.

To ensure cache isolation across GitHub repositories, Namespace automatically creates a cache volume for each GitHub repository where this label is in use. The cache volume tag follows the schema `github-git-mirror-{owner}-{repository}`.

For example, the following workflow definition asks for a git mirrors cache volume of 5 GB, and then uses Namespace's checkout action to clone the workflow's repository into the `my-repo` directory.

```yaml {5,8} theme={null}
jobs:
  tests:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-8x16-with-cache
      - nscloud-git-mirror-5gb

steps:
      - uses: namespacelabs/nscloud-checkout-action@v8
        name: Checkout
        with:
          path: my-repo
      - run: |
          cd my-repo && git status
```

## Toolchain caching

See [Toolchains](/content/docs/solutions/github-actions/caching/toolchains.md) for the full feature overview.

Add the label `nscloud-runner-tool-cache-{size}gb`, where `{size}` is an integer that indicates how large the cache volume storing the GitHub tools should be.

```yaml {5,8-9} theme={null}
jobs:
  tests:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-8x16-with-cache
      - nscloud-runner-tool-cache-20gb

steps:
      - uses: actions/setup-go@v6
      - uses: actions/setup-python@v6
```

## Custom cache identity

To specify custom cache tags, add a label `nscloud-cache-tag-{tag-name}`

```yaml {3} theme={null}
runs-on:
  - nscloud-ubuntu-22.04-amd64-4x16-with-cache
  - nscloud-cache-tag-my-custom-cache
  - nscloud-cache-size-100gb
```

## Restricting cache updates by branch

You can configure Cache Volumes to limit what git branches can perform updates to them. Add one or more `nscloud-cache-allow-commit-from-{branch-name}` labels, where `{branch-name}` is a git branch whose jobs are allowed to update the caches:

```yaml {7-8} theme={null}
jobs:
  tests:
    runs-on:
        - nscloud-ubuntu-22.04-arm64-4x16-with-cache
        - nscloud-cache-tag-cache-npm
        - nscloud-cache-size-100gb
        - nscloud-cache-allow-commit-from-main
        - nscloud-cache-allow-commit-from-default

steps:
      - uses: actions/setup-node@v6
```

## Restricting cache commits per job

Instead of protecting your cache per branch, you can also select which jobs may write to the cache. Add the label `nscloud-cache-exp-do-not-commit` to a job:

```yaml {7} theme={null}
jobs:
  tests:
    runs-on:
        - nscloud-ubuntu-22.04-arm64-4x16-with-cache
        - nscloud-cache-tag-cache-npm
        - nscloud-cache-size-100gb
        - nscloud-cache-exp-do-not-commit

steps:
      - uses: actions/setup-node@v6
```

## Remote Builders

See [Docker Builds](/content/docs/solutions/github-actions/docker-builds.md) for the full feature overview.

Remote Builders are enabled by default. When configuring runners with labels, apply builder-related settings with the `with-builders` suffix on your machine label, and add companion labels for specific behavior.

### Builds without output

When you want to test a build without pushing or loading it, use the `cacheonly` output type. This runs the full build and populates the cache, but skips the export step:

```yaml theme={null}
- uses: docker/build-push-action@v6
  with:
    context: .
    outputs: type=cacheonly
```

### Local caching

You can skip network transfer time by keeping a build local. First make sure you configure [a user cache](#attaching-a-cache-volume) with labels and then add the following label `nscloud-in-runner-builder`. When to keep a build local is covered in the [Docker Builds guide](/content/docs/solutions/github-actions/docker-builds.md).

```yaml {7} theme={null}
jobs:
  tests:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-8x32-with-cache
      - nscloud-cache-tag-example
      - nscloud-cache-size-100gb
      - nscloud-in-runner-builder

steps:
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
```

### Disabling Remote Builders

You can request that runners created for a particular workflow job do not use Remote Builders. Pass an additional configuration label `nscloud-no-remote-builders`, e.g.

```yaml {3} theme={null}
jobs:
  myjob:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-4x16-with-builders
      - nscloud-no-remote-builders
```

## Next steps

* [Cache Volumes](/content/docs/solutions/github-actions/caching.md)
* [Docker Builds](/content/docs/solutions/github-actions/docker-builds.md)
* [Runner Controls](/content/docs/solutions/github-actions/runner-controls.md)