Runner Controls

Runner Controls are settings for specific, situational needs: job scheduling, security, resource limits, networking, and container access.

Namespace lets you configure these as additional feature settings beyond your base runner configuration. You can pass these settings to a runner, for example container.privileged, github.run-id, or tailscale.spec. How you pass them depends on whether you use runner labels or a runner profile.

With runner profiles

The namespace-features: label cannot be used with profiles. Instead, append one or more ;key=value pairs directly to the profile name:

runs-on: namespace-profile-my-profile;container.privileged=true;container.host-pid-namespace=true

With runner labels

Pass the settings as a separate namespace-features: label (multiple values are separated by ;), and append the -with-features suffix to your machine label:

runs-on:
  - nscloud-ubuntu-22.04-amd64-4x8-with-features
  - namespace-features:container.privileged=true;container.host-pid-namespace=true

The -with-features suffix matters because GitHub assigns a job to any runner whose labels are a superset of the job's labels. Keeping the suffix on the machine label prevents jobs that don't request these features from being scheduled onto a feature-enabled runner.

Check each page below to see how to enable Runner Controls.

Relevant Links

• Concurrent runners - Limit how many runners can be active for a profile at once.
• Job ordering & priority - Control the order jobs are picked up with deterministic run-id assignment and numeric priority.
• Privileged workflows - Run jobs privileged or in the host PID namespace for sysctl, bubblewrap, and Nix.
• Landlock - Enable Landlock for advanced Linux workloads that apply their own sandbox restrictions.
• Swap space - Add a swap file so jobs survive short memory spikes without a larger shape.
• Tailscale - Connect a runner to your tailnet with the tailscale.spec feature.
• Access levels - Restrict which Namespace APIs a runner can reach with Permissive, Limited, or Restricted tiers.
• Running jobs in containers - Reach Namespace resources, caches, git mirrors, and the local builder from a container job.

Runner environment

Systemd

Namespace Runner images by default do NOT use Systemd. For some users this might require small changes to their workflows, e.g. replacing sudo systemctl start ... with sudo service start ....

If your workflows rely on systemd, an image using systemd is available upon request.

macOS bleeding-edge images

Namespace team continuously makes changes to macOS runner images to keep the software up-to-date and add new Xcode versions as soon as Apple releases them. More info on image updates.

To avoid regressions upcoming images go through multiple release stages before production release. This means that new Xcode versions become available to most customers with a short delay. However, it is possible to take advantage of new Xcode versions early. You can enroll your runners into using bleeding-edge macOS images.

Note: Images in the bleeding-edge channel have not passed the full set of validation checks and may contain regressions. We are happy to hear feedback from early users of these images via Namespace support channels. But enrolling should be done without expectation of perfect stability.

With runner profiles

Visit the runner profile editor and select the Use bleeding-edge images checkbox.

With runner labels

Add namespace-features:macos.channel=preview to the list of runner labels:

runs-on:
  - nscloud-macos-sequoia-arm64-6x14-with-features
  - namespace-features:macos.channel=preview

Hands-on support

Need help configuring your runners? Our team is here to assist:

• Technical support: Reach out to support@namespace.so to talk to one of our engineers.
• Community: Join our community Discord to learn about tips and best practices.