Manage queues

This page provides details on how to manage queues within a cluster of your Buildkite organization.

Setting up queues

When a new Buildkite organization is created, along with the automatically created default cluster (named Default cluster), a default queue (named default-queue) within this cluster is also created.

A cluster can be configured with multiple queues, each of which can be used to represent a specific combination of your build/agent infrastructure, based on:

Architecture (x86-64, arm64, Apple silicon, etc.)
Size of agents (small, medium, large, extra large)
Type of machine (Mac, Linux, Windows, etc.)

Some example queues might be linux_medium_x86, mac_large_silicon, etc.

Having individual queues according to these breakdowns allows you to scale a set of similar agents, which Buildkite can then report on.

Agent infrastructure

Buildkite provides support for managing Buildkite Agents in your own self-hosted infrastructure, as well as a Buildkite hosted infrastructure for managing these agents.

When setting up a queue, you can choose between configuring it with Buildkite Agents running in either of these types of infrastructure.

Learn more about how to set up and create a queue using either self-hosted agents (known as a self-hosted queue) or Buildkite hosted agents (known as a Buildkite hosted queue).

Be aware that it is not possible to create a queue that uses a mix of self-hosted and Buildkite hosted agents. If you do need to use a combination of these different agent types for your pipeline builds, create separate self-hosted and Buildkite hosted queues for these agents and use agent or queue tags, or a combination of both, to target the appropriate queues.

Furthermore, once a queue has been created, it is not possible to change its type from a self-hosted to a Buildkite hosted queue, or vice versa. If you do need to change your type of agent infrastructure, use a queue with the appropriate hosted queue type, or create a new queue to suit your new agent infrastructure.

Create a self-hosted queue

Self-hosted queues use Buildkite Agents installed in your own infrastructure to run your pipeline builds. New self-hosted queues can be created by a cluster maintainer using the Buildkite interface, as well as the REST API's or GraphQL API's create a queue feature.

For these API requests, the cluster ID value submitted in the request is the target cluster the queue will be created in.

When you create a new cluster through the Buildkite interface, this cluster automatically has an initial default queue.

Multiple self-hosted agents can connect to your self-hosted queue by ensuring that the agent is configured to use both of the following:

The cluster's agent token
The agent tag targeting your self-hosted queue

Using the Buildkite interface

To create a new queue using the Buildkite interface:

Select Agents in the global navigation to access the Clusters page.
Select the cluster in which to create the new queue.
On the Queues page, select New Queue to open the Create a new Queue page.
In the Create a key field, enter a unique key for the queue, which can only contain letters, numbers, hyphens, and underscores, as valid characters.
Select the Add description checkbox to enter an optional longer description for the queue. This description appears under the queue's key, which is listed on the Queues page, as well as when viewing the queue's details.
In the Select your agent infrastructure section, select Self hosted for your agent infrastructure.
Select Create Queue.

The new queue's details are displayed, indicating the queue's key and its description (if configured) underneath this key. Select Queues on the interface again to list all configured queues in your cluster.

Using the REST API

To create a new self-hosted agent queue using the REST API, run the following example curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "linux_small_amd",
    "description": "A small self-hosted AMD64 Linux agent."
  }'

where:

$TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your request needs access to in Buildkite.

{org.slug} can be obtained:
- From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.
- By running the List organizations REST API query to obtain this value from slug in the response. For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"
```

{cluster.id} can be obtained:
- From the Cluster Settings page of your target cluster. To do this:
  1. Select Agents (in the global navigation) > the specific cluster > Settings.
  2. Once on the Cluster Settings page, copy the id parameter value from the GraphQL API Integration section, which is the {cluster.id} value.
- By running the List clusters REST API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"
```

key (required) is displayed on the cluster's Queues pages, and this value can only contain letters, numbers, hyphens, and underscores, as valid characters.
description (optional) is a longer description for the queue, which appears under the queue's key, when listed on the Queues page, as well as when viewing the queue's details.

Using the GraphQL API

To create a new self-hosted agent queue using the GraphQL API, run the following example mutation:

mutation {
  clusterQueueCreate(
    input: {
      organizationId: "organization-id"
      clusterId: "cluster-id"
      key: "linux_small_amd"
      description: "A small self-hosted AMD64 Linux agent."
    }
  ) {
    clusterQueue {
      id
      uuid
      key
      description
      dispatchPaused
      hosted
      createdBy {
        id
        uuid
        name
        email
        avatar {
          url
        }
      }
    }
  }
}

where:

organizationId (required) can be obtained:
- From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.
- By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:
  
  Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:
```
query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}
```
  Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:
```
query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}
```
  Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

clusterId (required) can be obtained:
- From the Cluster Settings page of your target cluster. To do this:
  1. Select Agents (in the global navigation) > the specific cluster > Settings.
  2. Once on the Cluster Settings page, copy the cluster parameter value from the GraphQL API Integration section, which is the cluster.id value.
- By running the List clusters GraphQL API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:
```
query getClusters {
  organization(slug: "organization-slug") {
    clusters(first: 10) {
      edges {
        node {
          id
          name
          uuid
          color
          description
        }
      }
    }
  }
}
```

key (required) is displayed on the cluster's Queues pages, and this value can only contain letters, numbers, hyphens, and underscores, as valid characters.
description (optional) is a longer description for the queue, which appears under the queue's key, when listed on the Queues page, as well as when viewing the queue's details.

Create a Buildkite hosted queue

Buildkite hosted queues use Buildkite's hosted agent infrastructure to run your pipeline builds. New Buildkite hosted queues can be created by a cluster maintainer using the Buildkite interface, the REST API, or the GraphQL API.

When you create a Buildkite hosted queue, you can choose the machine type (Linux or macOS) and the capacity (small, medium, large, or extra large), known as the instance shape, of the Buildkite hosted agents that will run your builds.

Only one instance shape can be configured on a Buildkite hosted queue. However, depending on your pipeline's requirements, multiple Buildkite hosted agents of the queue's configured instance shape can be spawned automatically by Buildkite.

Using the Buildkite interface

To create a new Buildkite hosted queue using the Buildkite interface:

Select Agents in the global navigation to access the Clusters page.
Select the cluster in which to create the new queue.
On the Queues page, select New Queue to open the Create a new Queue page.
In the Create a key field, enter a unique key for the queue, which can only contain letters, numbers, hyphens, and underscores, as valid characters.
Select the Add description checkbox to enter an optional longer description for the queue. This description appears under the queue's key, which is listed on the Queues page, as well as when viewing the queue's details.
In the Select your agent infrastructure section, select Hosted for your agent infrastructure.
In the new Configure your hosted agent infrastructure section, select your Machine type (Linux or macOS).
If you selected Linux, within Architecture, you can choose between AMD64 (the default and recommended) or ARM64 architectures for the Linux machines running as hosted agents. To switch to ARM64, select Change, followed by ARM64 (AArch64).
Select the appropriate Capacity for your hosted agent machine type (Small, Medium or Large). Take note of the additional information provided in the new Hosted agents trial section, which changes based on your selected Capacity.
Select Create Queue.

The new queue's details are displayed, indicating the queue's key and its description (if configured) underneath this key. Select Queues on the interface again to list all configured queues in your cluster.

Using the REST API

To create a new Buildkite hosted queue using the REST API, run the following example curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "mac_small_silicon",
    "description": "macOS agents running on Apple silicon architecture.",
    "hostedAgents": {
      "instanceShape": "MACOS_M2_4X7"
    }
  }'

where:

$TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your request needs access to in Buildkite.

{org.slug} can be obtained:
- From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.
- By running the List organizations REST API query to obtain this value from slug in the response. For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"
```

{cluster.id} can be obtained:
- From the Cluster Settings page of your target cluster. To do this:
  1. Select Agents (in the global navigation) > the specific cluster > Settings.
  2. Once on the Cluster Settings page, copy the id parameter value from the GraphQL API Integration section, which is the {cluster.id} value.
- By running the List clusters REST API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"
```

key (required) is displayed on the cluster's Queues pages, and this value can only contain letters, numbers, hyphens, and underscores, as valid characters.
description (optional) is a longer description for the queue, which appears under the queue's key, when listed on the Queues page, as well as when viewing the queue's details.

hostedAgents (required) configures this queue to use Buildkite hosted agents, which makes this a Buildkite hosted queue, and defines the instance shape (within its instanceShape object) for this queue's Linux- or Mac-based Buildkite hosted agent. For example:
```
"hostedAgents": {
  "instanceShape": "LINUX_AMD64_2X4"
}
```

Using the GraphQL API

To create a new Buildkite hosted queue using the GraphQL API, run the following example mutation:

mutation {
  clusterQueueCreate(
    input: {
      organizationId: "organization-id"
      clusterId: "cluster-id"
      key: "mac_small_silicon"
      description: "macOS agents running on Apple silicon architecture."
      hostedAgents: {
        instanceShape: MACOS_M2_4X7
      }
    }
  ) {
    clusterQueue {
      id
      uuid
      key
      description
      dispatchPaused
      hosted
      hostedAgents {
        instanceShape {
          name
          size
          vcpu
          memory
        }
      }
      createdBy {
        id
        uuid
        name
        email
        avatar {
          url
        }
      }
    }
  }
}

where:

organizationId (required) can be obtained:
- From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.
- By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:
  
  Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:
```
query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}
```
  Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:
```
query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}
```
  Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

clusterId (required) can be obtained:
- From the Cluster Settings page of your target cluster. To do this:
  1. Select Agents (in the global navigation) > the specific cluster > Settings.
  2. Once on the Cluster Settings page, copy the cluster parameter value from the GraphQL API Integration section, which is the cluster.id value.
- By running the List clusters GraphQL API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:
```
query getClusters {
  organization(slug: "organization-slug") {
    clusters(first: 10) {
      edges {
        node {
          id
          name
          uuid
          color
          description
        }
      }
    }
  }
}
```

key (required) is displayed on the cluster's Queues pages, and this value can only contain letters, numbers, hyphens, and underscores, as valid characters.
description (optional) is a longer description for the queue, which appears under the queue's key, when listed on the Queues page, as well as when viewing the queue's details.

hostedAgents (required) configures this queue to use Buildkite hosted agents, which makes this a Buildkite hosted queue, and defines the instance shape (within its instanceShape object) for this queue's Linux- or Mac- based Buildkite hosted agent. For example:
```
hostedAgents: {
  instanceShape: LINUX_AMD64_2X4
}
```

Instance shape values for Linux

Specify the appropriate Instance shape for the instanceShape value in your API call.

Instance shape	Size	Architecture	vCPU	Memory
Instance shape	Instance shape	`LINUX_AMD64_2X4`	Size	Size	Small	Architecture	Architecture	AMD64	vCPU	vCPU	2	Memory	Memory	4 GB
Instance shape	Instance shape	`LINUX_AMD64_4X16`	Size	Size	Medium	Architecture	Architecture	AMD64	vCPU	vCPU	4	Memory	Memory	16 GB
Instance shape	Instance shape	`LINUX_AMD64_8X32`	Size	Size	Large	Architecture	Architecture	AMD64	vCPU	vCPU	8	Memory	Memory	32 GB
Instance shape	Instance shape	`LINUX_AMD64_16X64`	Size	Size	Extra Large	Architecture	Architecture	AMD64	vCPU	vCPU	16	Memory	Memory	64 GB
Instance shape	Instance shape	`LINUX_ARM64_2X4`	Size	Size	Small	Architecture	Architecture	ARM64	vCPU	vCPU	2	Memory	Memory	4 GB
Instance shape	Instance shape	`LINUX_ARM64_4X16`	Size	Size	Medium	Architecture	Architecture	ARM64	vCPU	vCPU	4	Memory	Memory	16 GB
Instance shape	Instance shape	`LINUX_ARM64_8X32`	Size	Size	Large	Architecture	Architecture	ARM64	vCPU	vCPU	8	Memory	Memory	32 GB
Instance shape	Instance shape	`LINUX_ARM64_16X64`	Size	Size	Extra Large	Architecture	Architecture	ARM64	vCPU	vCPU	16	Memory	Memory	64 GB

Instance shape values for Mac

Specify the appropriate Instance shape for the instanceShape value in your API call.

Instance shape	Size	vCPU	Memory
Instance shape	Instance shape	`MACOS_M2_4X7`	Size	Size	Small	vCPU	vCPU	4	Memory	Memory	7 GB
Instance shape	Instance shape	`MACOS_M2_6X14`	Size	Size	Medium	vCPU	vCPU	6	Memory	Memory	14 GB
Instance shape	Instance shape	`MACOS_M2_12X28`	Size	Size	Large	vCPU	vCPU	12	Memory	Memory	28 GB
Instance shape	Instance shape	`MACOS_M4_12X56`	Size	Size	Extra Large	vCPU	vCPU	12	Memory	Memory	56 GB

Pause and resume a queue

You can pause a queue to prevent any jobs of the cluster's pipelines from being dispatched to agents associated with this queue.

Enterprise feature

Queue pausing is only available to Buildkite customers with Pro and Enterprise plans.

To pause a queue:

Select Agents in the global navigation to access the Clusters page.
Select the cluster with the queue to pause.
On the Queues page, select the queue to pause.
On the queue's details page, select Pause Queue.
Enter an optional note in the confirmation dialog, and select Pause Queue to pause the queue.

Note: Use this note to explain why you're pausing the queue. The note will be displayed on the queue's details page and on any affected builds.

Jobs already dispatched to agents in the queue before pausing will continue to run. New jobs that target the paused queue will wait until the queue is resumed.

Since trigger steps do not rely on agents, these steps will run, unless they have dependencies waiting on the paused queue. The behavior of the triggered jobs depends on their configuration:

If a triggered job targets a paused queue, the job will wait until the queue is resumed.
If a triggered job does not target the paused queue, the job will run as usual.

To resume a queue:

Select Agents in the global navigation to access the Clusters page.
Select the cluster with the queue to resume.
On the Queues page, select the queue to resume.
On the queue's details page, select Resume Queue.

Jobs will resume being dispatched to the resumed queue as usual, including any jobs waiting to run.