Pipelines

A collection of common tasks with pipelines using the GraphQL API.

You can test out the Buildkite GraphQL API using the Buildkite explorer. This includes built-in documentation under the Docs panel.

Create a pipeline

Create a pipeline programmatically.

First, get the organization ID, team ID, and cluster ID (uuid) values:

query getOrganizationTeamAndClusterIds {
  organization(slug: "organization-slug") {
    id
    teams(first:500) {
      edges {
        node {
          id
          slug
        }
      }
    }
    clusters(first: 10) {
      edges {
        node {
          name
          uuid
          color
          description
        }
      }
    }
  }
}

The relevant cluster's uuid value is the cluster-id value used in the next step.

Then, create the pipeline:

mutation createPipeline {
  pipelineCreate(input: {
    organizationId: "organization-id"
    name: "pipeline-name"
    repository: {url: "repo-url"}
    clusterId: "cluster-id"
    steps: { yaml: "steps:\n - command: \"buildkite-agent pipeline upload\"" }
    teams: { id: "team-id" }
  }) {
    pipeline {
      id
      name
      teams(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }
}

When setting pipeline steps using the API, you must pass in a string that Buildkite parses as valid YAML, escaping quotes and line breaks.

To avoid writing an entire YAML file in a single string, you can place a pipeline.yml file in a .buildkite directory at the root of your repo, and use the pipeline upload command in your pipeline steps to tell Buildkite where to find it. This means you only need the following:

steps: { yaml: "steps:\n - command: \"buildkite-agent pipeline upload\"" }

Deriving a pipeline slug from the pipeline's name

Pipeline slugs are derived from the pipeline name you provide when the pipeline is created (unless you use the optional slug parameter to specify a custom slug).

This derivation process involves converting all space characters (including consecutive ones) in the pipeline's name to single hyphen - characters, and all uppercase characters to their lowercase counterparts. Therefore, pipeline names of either Hello there friend or Hello There Friend are converted to the slug hello-there-friend.

The maximum permitted length for a pipeline slug is 100 characters.

The following regular expression is used to derive and convert the pipeline name to its slug:

/\A[a-zA-Z0-9]+[a-zA-Z0-9\-]*\z/

Any attempt to create a new pipeline with a name that matches an existing pipeline's name, results in an error.

Get a list of recently created pipelines

Get a list of the 500 most recently created pipelines.

query RecentPipelineSlugs {
  organization(slug: "organization-slug") {
    pipelines(first: 500) {
      edges {
        node {
          slug
        }
      }
    }
  }
}

Get a pipeline's ID

Get a pipeline's ID which can be used in other queries.

query {
  pipeline(slug:"organization-slug/pipeline-slug") {
    id
  }
}

Get a pipeline's UUID

Get a pipeline's UUID by searching for it in the API. Search term can match a pipeline slug.

Note: Pipeline slugs are modifiable and can change

query GetPipelineUUID {
  organization(slug: "organization-slug") {
    pipelines(first: 50, search: "part of slug") {
      edges {
        node {
          slug
          uuid
        }
      }
    }
  }
}

Get a pipeline's information

You can get specific pipeline information for each of your pipeline. You can retrieve information for each build, jobs, and any other information listed on this page.

query GetPipelineInfo {
  pipeline(uuid: "pipeline-uuid") {
    slug
    uuid
    builds(first:50){
      edges {
        node {
          state
          message
        }
      }
    }
  }
}

Get pipeline metrics

The Pipelines page in Buildkite shows speed, reliability, and builds per week, for each pipeline. You can also access this information through the API.

query AllPipelineMetrics {
  organization(slug: "organization-slug") {
    name
    pipelines(first: 50) {
      edges {
        node {
          name
          metrics {
            edges {
              node {
                label
                value
              }
            }
          }
        }
      }
    }
  }
}

Delete a pipeline

First, get the ID of the pipeline you want to delete. Then, use the ID to delete the pipeline:

mutation PipelineDelete {
  pipelineDelete(input: {
    id: "pipeline-id"
  })
  {
    deletedPipelineID
  }
}

Delete multiple pipelines

First, get the IDs of the pipelines you want to delete. Then, use the IDs to delete multiple pipelines:

mutation PipelinesDelete {
  pipeline1: pipelineDelete(input: {
    id: "pipeline1-id"
  })
  {
    deletedPipelineID
  }

  pipeline2: pipelineDelete(input: {
    id: "pipeline2-id"
  })
  {
    deletedPipelineID
  }
}

Update pipeline schedule with multiple environment variables

You can set multiple environment variables on a pipeline schedule by using the new-line value \n as a delimiter.

mutation UpdateSchedule {
  pipelineScheduleUpdate(input:{
    id: "schedule-id"
    env: "FOO=bar\nBAR=foo"
  }) {
    pipelineSchedule {
      id
      env
    }
  }
}

Archive a pipeline

First, get the ID of the pipeline you want to archive. Then, use the ID to archive the pipeline:

mutation PipelineArchive {
  pipelineArchive(input: {
    id: "pipeline-id"
  })
  {
    pipeline {
      id
      name
    }
  }
}

Archive multiple pipelines

First, get the IDs of the pipelines you want to archive. Then, use the IDs to archive the pipelines:

mutation PipelinesArchive {
  pipeline1: pipelineArchive(input: {
    id: "pipeline1-id"
  })
  {
    pipeline {
      id
      name
    }
  }

  pipeline2: pipelineArchive(input: {
    id: "pipeline2-id"
  })
  {
    pipeline {
      id
      name
    }
  }
}

Unarchive a pipeline

First, get the ID of the pipeline you want to unarchive. Then, use the ID to unarchive the pipeline:

mutation PipelineUnarchive {
  pipelineUnarchive(input: {
    id: "pipeline-id"
  })
  {
    pipeline {
      id
      name
    }
  }
}

Unarchive multiple pipelines

The process for unarchiving multiple pipelines is similar to that for archiving multiple pipelines.

However, use the field pipelineUnrchive (in pipeline1: pipelineUnarchive(input: { ... }), etc.) instead of pipelineArchive.