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

Examples:

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.

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:

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 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, 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.

Example: caching NPM packages

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

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:

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 for the full feature overview.

Configure the cache volume with the required set of labels, 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.

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 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.

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 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.

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}

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:

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:

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 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:

- 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 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.

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.

jobs:
  myjob:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-4x16-with-builders
      - nscloud-no-remote-builders

Next steps

• Cache Volumes
• Docker Builds
• Runner Controls