> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Buildkite Jobs on Namespace

Namespace provides ephemeral, self-hosted Buildkite agents without requiring you to operate agent infrastructure.

Prefer to manage the integration through Buildkite? Buildkite Hosted Agents use Namespace infrastructure and are configured directly in Buildkite.

[Learn about Buildkite Hosted Agents →](https://buildkite.com/docs/pipelines/hosted-agents/overview)

## How it works

Connecting a Buildkite organization creates a Namespace-managed queue and an agent token in either a new **Namespace Cluster** or an existing Buildkite cluster.
A Buildkite webhook notifies Namespace when a job is scheduled on that cluster.
Namespace then provisions an isolated instance, starts an agent for the queue, runs the job, and tears the instance down when the job completes.

You can select the operating system, architecture, instance shape, base image, and persistent cache for each step using [agent tags](https://namespace.so/docs/solutions/buildkite-agents/configuration.md).

## Getting Started

### 1. Create a Buildkite API access token

[Create an API access token](https://buildkite.com/user/api-access-tokens/new) for the Buildkite organization you want to connect. Namespace uses this token for initial setup, ongoing build reconciliation, and build annotations, so its expiry must be set to **Never**. The token can be revoked at any time through the Buildkite UI.
Enable these REST API scopes:

* `read_pipelines`
* `read_builds` and `write_builds`
* `read_clusters` and `write_clusters`
* `read_organizations`

> [!NOTE]
>
> The "No organization" access option is not supported. Make sure that you select a valid organization for your token.

### 2. Connect your Buildkite organization

Open **Buildkite → Get started** in the [Namespace dashboard](https://cloud.namespace.so/workspace/buildkite). If another organization is already connected, select **Connect organization** from the [Organizations page](https://cloud.namespace.so/workspace/buildkite/organizations) instead.

Enter the API token and click **Next**. Namespace uses the token to identify your Buildkite organization and list its clusters.

### 3. Select a cluster and queue

Choose where Namespace should create its managed queue:

* Select **Create a new cluster** to create the **Namespace Cluster** with a `default` queue.
* Select an existing cluster to add a queue to it. Enter a queue name, or keep the default name, `namespace`.

Configure any optional connection settings, then click **Associate**. Namespace creates the cluster if needed, creates the queue and its agent token, and displays the webhook setup instructions. Copy the generated webhook URL for the next step.

### 4. Configure the Buildkite webhook

On the next page, click on **Create new Webhook** and copy and paste the provided webhook URL and token.

![Buildkite webhook configuration for Namespace](https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/buildkite-agents/webhook.png?fit=max\&auto=format\&n=MoefQ379UcpNU680\&q=85\&s=c8b0a2fcdd652ada40042a6d00bb286c)

Select the following events in the Buildkite webhook interface:

* `ping`
* `job.scheduled`
* `job.started`
* `job.finished`

![Buildkite webhook events configuration for Namespace](https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/buildkite-agents/webhook_events.png?fit=max\&auto=format\&n=MoefQ379UcpNU680\&q=85\&s=0f1179b63dbcf1e28b4e0fd346e1ec9c)

Make sure the webhook is enabled for **All Pipelines**.

![Buildkite pipelines configuration for Namespace](https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/buildkite-agents/pipelines.png?fit=max\&auto=format\&n=MoefQ379UcpNU680\&q=85\&s=aade79d6f5207f70613e456a4b340ded)

Click **Add Webhook Notification**, then return to Namespace. The connection becomes active after Namespace receives the webhook ping.

### 5. Add a pipeline to the selected cluster

In your Buildkite pipeline's settings, select the cluster you chose during setup under **General > Cluster**. If you added a queue to an existing cluster, set the pipeline or step's `queue` agent tag to the queue name you chose:

```yaml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
agents:
  queue: "namespace"
```

## Checking out code from GitHub & Cursor Origin

Namespace checks out your repository before each Buildkite job runs. Public repositories work with no extra configuration; private repositories need credentials, as described below.

### Cloning with HTTPS

Cloning public repositories over HTTPS requires no additional configuration.

**To clone private GitHub repositories**, add your GitHub credentials to your Buildkite organization in Namespace:

1. Connect your GitHub account through [Code providers](https://cloud.namespace.so/workspace/code/providers).
2. Open **Buildkite → Organizations** in the [Namespace dashboard](https://cloud.namespace.so/workspace/buildkite/organizations) and select your Buildkite organization.
3. Click **Edit Secrets**, then **Add another secret**.
4. Select **GitHub Credentials** from the dropdown, select your GitHub account, and then click **Save Variables**.

Namespace will now use short-lived credentials provided by the GitHub App integration to check out code.

**To clone a private Cursor Origin repository:**

1. Connect Buildkite to Cursor so Cursor can start Buildkite jobs for the repository.
2. Connect Cursor Origin through [Code Providers](https://cloud.namespace.so/workspace/code/providers) so Namespace can check out the repository.
3. Configure the pipeline to use a Namespace-managed queue as described in [Getting Started](#getting-started).

### Cloning with SSH

You can configure cloning over SSH by uploading your private key either to Namespace Vault or as a secret in Buildkite. Currently, [signed pipelines](https://namespace.so/docs/solutions/buildkite-agents/configuration.md#verifying-signed-buildkite-pipelines) with SSH checkout are supported only with secrets stored in Namespace.

> [!NOTE]
>
> Cloning over SSH is not supported yet for Cursor Origin repositories.

To configure cloning over SSH in Namespace:

1. Upload your private key as a [secret](https://namespace.so/docs/architecture/storage/secrets.md#create-secret), using either the [Vault dashboard](https://cloud.namespace.so/workspace/vars) or CLI command

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
nsc vault add --from_file /path/to/private/key --description "SSH private key"
```

2. In the [Namespace dashboard](https://cloud.namespace.so/workspace/buildkite), click on **Edit Secrets** and then **Add another secret**.
3. Select **SSH Key** from the dropdown, select your key, and then click **Save Variables**.

![SSH private key configuration](https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/buildkite-agents/sshkey.png?fit=max\&auto=format\&n=MoefQ379UcpNU680\&q=85\&s=d7a19c1b45587c69e8b4ecebce03bbbf)

If you prefer to store your SSH key in Buildkite, follow Buildkite's [code access setup for self-hosted agents](https://buildkite.com/docs/agent/self-hosted/code-access). Store your private key as a Buildkite secret, then set `checkout.ssh_secret` on each of your pipeline's steps that require SSH access:

```yaml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
steps:
  - label: "Build"
    command: "make build"
    checkout:
      ssh_secret: "MY_SSH_KEY"
```

### Git snapshots

For faster checkouts of large GitHub or Cursor Origin repositories, jobs can use a pre-fetched snapshot instead of a Git clone. See [Git Snapshots](https://namespace.so/docs/solutions/buildkite-agents/git-snapshots.md).

## Next Steps

**[Managing Queues](https://namespace.so/docs/solutions/buildkite-agents/managing-queues.md)**. Register additional Buildkite queues with Namespace, route jobs to them, and unregister the ones you no longer need.

**[Configure Buildkite Agents](https://namespace.so/docs/solutions/buildkite-agents/configuration.md)**. Choose compute resources, base images, and persistent caches with agent tags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.