GitHub Integration

To start, install the Namespace GitHub application to the organization where you want to use Namespace products. Follow the instructions given:

• Open the Dashboard on https://cloud.namespace.so
• On the Integrations page, click on Add Organisation under GitHub Actions 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.

Authentication

Namespace uses GitHub OIDC provider to authenticate GitHub Actions jobs. For this, you need to enable your job or workflow to request GitHub's OIDC JWT ID tokens by adding id-token: write permissions, which allows your job/workflow to request OIDC JWT ID tokens.

You can add the permission at the workflow level, for example:

name: Example workflow
permissions:
  id-token: write

In this case, all the jobs within the workflow may use Namespace.

If you need to authorize only a single job, set the permission within that job. For example:

name: Example workflow
jobs:
  example_job:
    permissions:
      id-token: write

Namespace GitHub actions

namespacelabs/nscloud-setup

namespacelabs/nscloud-setup is a GitHub action configuring Namespace access. It installs and configures the Namespace CLI nsc in your GitHub Actions workflow.

Example:

jobs:
  deploy:
    name: Ephemeral cluster
    runs-on: ubuntu-latest
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install and configure Namespace CLI
        uses: namespacelabs/nscloud-setup@v0
      - name: Create an ephemeral cluster
        run: |
          nsc cluster create

namespacelabs/nscloud-setup-buildx-action

namespacelabs/nscloud-setup-buildx-action is a GitHub action that configures buildx to use a Namespace remote builder.

Example:

jobs:
  docker:
    runs-on: ubuntu-latest
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install and configure Namespace CLI
        uses: namespacelabs/nscloud-setup@v0
      - name: Configure buildx
        uses: namespacelabs/nscloud-setup-buildx-action@v0
      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          push: true
          tags: user/app:latest

This action uses nsc, the Namespace CLI. You can add it to your workflow using the namespacelabs/nscloud-setup GitHub action.

namespacelabs/nscloud-cluster-action

namespacelabs/nscloud-cluster-action is a GitHub action that creates a Namespace Kubernetes cluster. It also downloads and preconfigures kubectl to grant access to the cluster.

Example:

jobs:
  deploy:
    name: Ephemeral cluster
    runs-on: ubuntu-latest
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install and configure Namespace CLI
        uses: namespacelabs/nscloud-setup@v0
      - name: Create a Namespace cluster
        uses: namespacelabs/nscloud-cluster-action@v0
      - name: Apply configurations
        run: |
          kubectl apply -f foo/bar.yaml

This action uses nsc, the Namespace CLI. You can add it to your workflow using the namespacelabs/nscloud-setup GitHub action.