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 likenscloud-{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
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:-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-cacheto 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.-]+).
/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
Usenscloud-cache-action to mount the volume under the paths you want to cache.
Sharing a cache volume
Add thenscloud-cache-tag-{tag} label. Jobs carrying the same tag label share one cache volume,
even if their machine labels differ:
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 labelnscloud-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.
Git checkout caching
See Git Checkouts for the full feature overview. Add the runner labelnscloud-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.
Toolchain caching
See Toolchains for the full feature overview. Add the labelnscloud-runner-tool-cache-{size}gb, where {size} is an integer that indicates how large the cache volume storing the GitHub tools should be.
Custom cache identity
To specify custom cache tags, add a labelnscloud-cache-tag-{tag-name}
Restricting cache updates by branch
You can configure Cache Volumes to limit what git branches can perform updates to them. Add one or morenscloud-cache-allow-commit-from-{branch-name} labels, where {branch-name} is a git branch whose jobs are allowed to update the caches:
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 labelnscloud-cache-exp-do-not-commit to a job:
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 thewith-builders suffix on your machine label, and add companion labels for specific behavior.
The
with-builders suffix is required in order to apply any builder-related configuration.Builds without output
When you want to test a build without pushing or loading it, use thecacheonly output type.
This runs the full build and populates the cache, but skips the export step:
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 labelnscloud-in-runner-builder. When to keep a build local is covered in the Docker Builds guide.
Disabling Remote Builders
You can request that runners created for a particular workflow job do not use Remote Builders. Pass an additional configuration labelnscloud-no-remote-builders, e.g.