Portals

Getting started

To get started with portals, as a Buildkite organization administrator, access the Portals feature to begin creating a portal (for example, to create an example portal that triggers a build on the main branch of a pipeline):

1. Select Settings in the global navigation to access the Organization Settings page.

2. Select Integrations > Portals to access your organization's Portals page.

3. Select the Create a portal button. Note that if existing portals are present, select the New Portal button instead.

   At a minimum, a portal requires a Name and GraphQL query, which are used to generate a unique endpoint, and a GraphQL document.

4. Specify your portal's Name (for example, Trigger main build).

5. Specify the definition for the operation that your portal is allowed to perform in GraphQL query. For example, use the following GraphQL mutation:

   mutation triggerBuild {
   buildCreate(input:{
     branch: "main",
     commit: "HEAD,"
     pipelineID: "pipeline-id",
   }) {
       build {
         url
       }
     }
   }
   

   Tip: You can get the GraphQL pipeline ID (for example, a value looking similar to something like UGlwZWxpbmUtLS0wMTkzMDkxZC1lOTIUzzRhMWEtYWQ0NS1jMWJhNTA2N2RiMzQ=) from your pipeline settings.

6. After completing these required fields and any others for this portal, select Save Portal to create the portal.

   A new HTTP endpoint is generated, along with a corresponding portal token (a type of access token known as an admin-level portal token), which you'll need to use later for authentication.

7. Save this portal token to somewhere secure, as you won't be able to access its value again through the Buildkite interface.

   Note: This portal token is referred to as an admin-level one, since it grants Buildkite organization administrator-access privileges to this Buildkite organization.

8. Make a request to your new endpoint. You can access it using the following curl command, replacing the organization slug with your own.

   For example:

   curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d "{}" \
     -X POST "https://portal.buildkite.com/organizations/my-organization/portals/trigger-main-build"
   

Voila! You've just created and executed a portal.

Endpoint

Each portal has a unique endpoint served from https://portal.buildkite.com with the following URL structure:

https://portal.buildkite.com/organizations/{organization.slug}/portals/{portal}

All requests must be HTTP POST requests with application/json encoded bodies.

Defining multiple operations

Multiple GraphQL operations can be defined within a single portal GraphQL document. This enables grouping related queries and mutations such as those used in CLI tools or custom workflows under a single portal token for more streamlined usage.

The following example defines two operations in the same document—one to fetch recent builds, and another to trigger a new build:

  query GetBuilds($pipelineSlug: ID!) {
    pipeline(slug: $pipelineSlug) {
      builds(last: 10, branch: "main") {
        edges {
          node {
            url
          }
        }
      }
    }
  }

  mutation triggerBuild($pipelineID: ID!) {
    buildCreate(input:{
      branch: "main",
      commit: "HEAD",
      pipelineID: $pipelineID,
    }) {
      build {
        url
      }
    }
  }

An example request for running the GetBuilds operation:

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pipelineSlug": "organization-slug/pipeline-slug" }' \
  -X POST "https://portal.buildkite.com/organizations/my-organization/portals/portal-slug?operation_name=GetBuilds"

Authentication

Similar to the Buildkite REST and GraphQL APIs, portals are authenticated with the associated portal token generated for a given portal.

For example:

curl -H "Authorization: Bearer $TOKEN" https://portal.buildkite.com/organizations/my-org/portals/my-portal

Passing arguments

GraphQL operations may include arguments which can be provided as part of the JSON request body.

For example, given a portal that uses the following GraphQL query:

query GetTotalBuildRunTime($build_slug: ID) {
  build(slug: "organization-slug/pipeline-slug/build-number") {
    pipeline {
      name
    }
    url
    startedAt
    finishedAt
  }
}

Calling this specific portal would then require build_slug to be included as part of the HTTP request.

e.g.

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "build_slug": "organization-slug/pipeline-slug/build-number" }' \
  -X POST "https://portal.buildkite.com/organizations/my-organization/portals/get-total-build-run-time"

Customer preview

While portals are in customer preview, the creation of portals is restricted to organization administrators.