Running jobs in containers

Namespace Runners support using custom containers for GitHub Jobs. When a job runs inside a container, reaching Namespace resources, caches, git mirrors, and the local builder each need a small amount of extra mount and setup configuration.

Accessing Namespace resources from containers

To access Namespace resources from within a container, extra configuration is required. In particular, the directory /var/run/nsc/ must be mounted into the container, and namespacelabs/nscloud-setup needs to be run. See the following snippet for a working example of accessing Bazel:

tests:
  runs-on: namespace-profile-my-profile-for-containers

  container:
    image: <my-image-ref>
    volumes:
      - /var/run/nsc/:/var/run/nsc/

    steps:
      - uses: actions/checkout@v4
      - uses: namespacelabs/nscloud-setup@v0
      - name: Setup Bazel cache
        run: |
          nsc bazel setup --remote=false --bazelrc /etc/bazel.bazelrc
      - name: Bazel test
        run: |
          bazel --bazelrc=/etc/bazel.bazelrc test //..

Accessing cache volumes from containers

To access Cache volumes from within a container, additional configuration is required. For example, when using an Ubuntu-based custom image, the following snippet provides a working, minimal example:

tests:
  runs-on: namespace-profile-my-profile-for-containers

  container:
    image: <my-image-ref>
    env:
      NSC_CACHE_PATH: ${{ env.NSC_CACHE_PATH }} # env.NSC_CACHE_PATH contains the path to cache volume directory, that is `/cache`.
    volumes:
      - /cache:/cache # Where the cache volume is mounted.
    options: --cap-add=SYS_ADMIN # Required to by nscloud-cache-action to call `mount`.

  steps:
    - uses: actions/checkout@v4

    - name: Install sudo
      run: |
        apt-get update -y && apt-get install -y sudo

    - name: Setup cache
      uses: namespacelabs/nscloud-cache-action@v1
      with:
        cache: rust

Please see our nscloud-cache-action documentation for details.

Accessing Git mirrors from containers

If your workflow runs in a container, additional configuration is required to use cached Git Repositories:

tests:
  runs-on: namespace-profile-my-profile-for-containers

  container:
    image: <my-image-ref>
    env:
      NSC_GIT_MIRROR: ${{ env.NSC_GIT_MIRROR }} # env.NSC_GIT_MIRROR contains the path to the git mirror directory.
    volumes:
      - /gitmirror:/gitmirror # Where the git mirror cache is mounted.

  steps:
    - name: Checkout with Namespace Git mirrors cache
      uses: namespacelabs/nscloud-checkout-action@v8

Please see our nscloud-checkout-action documentation for details.

Using local build caching from containers

While Remote Builders provide the best performance for most scenarios, in-runner builders (locally cached) excel when building massive images (10GB+). Keeping the build local skips network transfer time. To access in-runner builders from within a container, additional configuration is required.

Enable local build caching

With runner profiles
With runner labels

To enable this feature, just open the runner profile configuration and add a cache volume. Next, select Locally cached for your Docker builds.

If using runner labels, first make sure you configure a user cache with labels and then add the following label nscloud-in-runner-builder.

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

Update your workflow

In the job step definition, you need to forward the buildkit socket and create a builder inside the container that uses the parent:

jobs:
  myjob:
    container:
      image: <my-image-ref>
      volumes:
        - /var/run/buildkit/buildkitd.sock:/var/run/buildkit/buildkitd.sock
  steps:
    - uses: actions/checkout@v4
    - ...
    - name: Configure builder
      run: |
        docker buildx create --driver remote --name parent --use unix:///var/run/buildkit/buildkitd.sock
    - ...

Products

Platform

Administration

Accessing Namespace resources from containers

Accessing cache volumes from containers

Accessing Git mirrors from containers

Using local build caching from containers

Enable local build caching

Update your workflow

Next steps

​Accessing Namespace resources from containers

​Accessing cache volumes from containers

​Accessing Git mirrors from containers

​Using local build caching from containers

Enable local build caching

Update your workflow

​Next steps

Accessing Namespace resources from containers

Accessing cache volumes from containers

Accessing Git mirrors from containers

Using local build caching from containers

Next steps