GitHub Runners

Namespace supports fast, secure, and affordable Runners for your GitHub Actions.

Namespace manages GitHub Runners in ephemeral virtual machines that boot in a few seconds and suspend themselves immediately after the CI job completes.


To start, install the Namespace CI Runners application to the organization where you want to use Namespace-managed GitHub Runners. Follow the instructions given:

  • Open the Dashboard at cloud.namespace.so
  • On the Integrations page, click on Add Organisation under the GitHub Runners section.
  • In the pop-up window, select the organization to which you want to install the Namespace app.
  • Finally, choose if you want to install the app to all repositories or just a selection.

After installing the Namespace app, you can start using Namespace-managed GitHub Actions Runners.

Using Namespace GitHub Runners

To schedule a GitHub Actions job on Namespace GitHub runners, change the runs-on option in your workflow job to runs-on: nscloud. For example:

- runs-on: ubuntu-20.04
+ runs-on: nscloud
name: Build Docker image

Table of Supported Labels

To use different runner CPU architectures or machine shapes, you can specify one of the following labels.

nscloudUbuntu 22.04AMD 64-bit416 GB
nscloud-amd64Ubuntu 22.04AMD 64-bit416 GB
nscloud-ubuntu-22.04-amd64Ubuntu 22.04AMD 64-bit416 GB
nscloud-ubuntu-22.04-amd64-4x16Ubuntu 22.04AMD 64-bit416 GB
nscloud-arm64Ubuntu 22.04ARM 64-bit416 GB
nscloud-ubuntu-22.04-arm64Ubuntu 22.04ARM 64-bit416 GB
nscloud-ubuntu-22.04-arm64-4x16Ubuntu 22.04ARM 64-bit416 GB

Note that only one nscloud label is allowed in the run-on field of your workflow file. If the run-on specifies more than one nscloud label or invalid ones, the workflow job will not be scheduled.

Namespace also supports custom machine shapes, so you can configure your runner to a bigger or smaller machine of what provided by the table of well-known labels above. You can specify the machine shape with the label format as follows:

run-on: nscloud-{os}-{arch}-{vcpu}x{mem}


  • {os}: is the operating system image to use. Today only "ubuntu-22.04" is allowed.
  • {arch}: can either be "amd64" or "arm64".
  • {vcpu}: integer number of vCPU.
  • {mem}: integer number for memory in GB.

For example, a 2 vCPU 4 GB of memory ARM runner can be created with the following label:

run-on: nscloud-ubuntu-22.04-arm64-2x4

Note that the runner may not be created if you specify a machine shape that is not enabled for your workspace or if you run out of available concurrent capacity.

Integration with other Namespace products

Using Namespace GitHub Runners, you get seamless integrations with other Namespace products: Remote Builds, Ephemeral Clusters, and Container Registry.

There is no need to configure additional permissions or run namespacelabs/nscloud-setup action - GitHub runner, by default, is configured to use Namespace. So you can use nsc CLI from your GitHub Actions workflow or Namespace GitHub actions. For example:

    name: Create ephemeral cluster
    runs-on: nscloud
      contents: read
      - name: Checkout
        uses: actions/checkout@v3
      - name: Create an ephemeral cluster
        run: |
          nsc cluster create

Debugging GitHub Actions jobs

GitHub hosted runners are ephemeral and managed by GitHub. When the job fails, there is no way to SSH into the runner, check logs, or debug the state. With Namespace GitHub Runners, you can do this.

You need to know the Runner ID to SSH into a Namespace GitHub Runner. From the below example, we can see that the Runner's name was nsc-runner-5dhbr540ug1gc. So on the Namespace side, the assigned Runner ID is 5dhbr540ug1gc.

job completed in nscloud

The job execution will also be available in the Namespace dashboard. The Runner ID 5dhbr540ug1gc below links to the job started by our example django-app repository.

runs view on nscloud dashboard

If you click on it, you can check the Runner's logs and SSH into the instance, and debug the live GitHub run directly.

ssh view on nscloud dashboard

You can quickly SSH also through our nsc CLI.

nsc cluster ssh 5dhbr540ug1gc

Inside the Runner, you can, for example, check running containers using docker or nerdctl CLI - docker ps, check container logs with docker logs <container-id>, the running Linux processes, etc.

What's Next?