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

How it works

Connecting a Buildkite organization creates a Namespace Cluster with a default queue and an agent token. 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.

Reach out to get enrolled into Namespace-managed agents.

Contact support

Getting Started

Create a Buildkite API access token

Create an API access token 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

Connect your Buildkite organization

Open Buildkite → Jobs in the Namespace dashboard, then enter the API token and your Buildkite organization slug, and then click Associate.

Namespace creates the Namespace Cluster, its default queue, and an agent token in your Buildkite organization.

Configure the Buildkite webhook

Copy the provided webhook URL and token. Click on Create new Webhook and copy and paste the provided webhook URL and token. Select the following events in the Buildkite webhook interface:

  • ping
  • job.scheduled
  • job.started
  • job.finished
Buildkite webhook configuration for Namespace

Limit the webhook to Pipelines in Clusters... → Namespace Cluster.

Add a pipeline to the Namespace Cluster

In your Buildkite pipeline's settings, select Namespace Cluster under General > Cluster to ensure that jobs for that pipeline are eligible to run on Namespace agents.

Next Steps

Configure Buildkite Agents. Choose compute resources, base images, and persistent caches with agent tags.