GitHub Runners

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

Onboarding

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:

  jobs:
    build:
-     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.

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}

Where:

• {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

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:

jobs:
  deploy:
    name: Create ephemeral cluster
    runs-on: nscloud
    permissions:
      contents: read
    steps:
      - 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.

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.

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

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?

• Chat with the team on Discord