pybuildkite

Warnings

• breaking The underlying Buildkite REST API transitioned from v1 to v2, introducing breaking changes such as renaming 'project' properties to 'pipeline' and removing certain endpoints. While `pybuildkite` v1.x largely aligns with Buildkite API v2, users migrating from very old `pybuildkite` versions or those whose code directly relied on v1 API semantics should consult `pybuildkite`'s release notes and the official Buildkite API migration guide (https://buildkite.com/docs/api/rest#migrating-from-v1-to-v2).
  Fix: Upgrade to the latest `pybuildkite` version and review your code for usage of deprecated API endpoints or 'project' terminology. Refer to Buildkite's official API documentation for current endpoint structures.
• gotcha When dealing with API endpoints that return large datasets, it's crucial to implement pagination. By default, `pybuildkite` might return a limited number of items per request (e.g., 100). Failing to handle pagination can lead to incomplete data retrieval.
  Fix: Use the `with_pagination=True` parameter and iterate through `next_page` results, or specify the `per_page` parameter to control the number of items returned per request. Example: `builds_response = buildkite.builds().list_all(page=1, with_pagination=True); while builds_response.next_page: ...`
• gotcha Buildkite API access tokens are sensitive credentials. Buildkite has updated its security policies, including new tokens being single-organization by default and deprecating retrieval of agent tokens via GraphQL for newly created tokens. Using compromised or overly permissive tokens is a significant security risk.
  Fix: Always use API tokens with the least privilege necessary. Store tokens securely (e.g., environment variables, secret management systems) and avoid hardcoding them. Regularly rotate tokens and review their scopes on the Buildkite dashboard.
• gotcha The primary class for interacting with the Buildkite API is named `Buildkite` (note the lowercase 'k'). Incorrectly using `BuildKite` (uppercase 'K') due to case sensitivity will result in an `ImportError` or `NameError`.
  Fix: Ensure correct capitalization when importing: `from pybuildkite.buildkite import Buildkite`.

Install

• pip install pybuildkite Install stable version

Imports

• Buildkite

  from pybuildkite.buildkite import Buildkite

  The class name is 'Buildkite' (lowercase 'k'). Using 'BuildKite' (uppercase 'K') will result in an ImportError or NameError.
• BuildState

  from pybuildkite.buildkite import BuildState

  Used for filtering builds by their state (e.g., RUNNING, SCHEDULED).

Quickstart

Initializes the Buildkite client with an API access token (preferably from an environment variable) and demonstrates how to fetch organization details and list builds for a specific pipeline. It also includes a commented-out example for creating a new build.

import os
from pybuildkite.buildkite import Buildkite, BuildState

# Get your Buildkite API access token from environment variables
api_access_token = os.environ.get('BUILDKITE_API_ACCESS_TOKEN', 'YOUR_API_ACCESS_TOKEN_HERE')
org_slug = os.environ.get('BUILDKITE_ORGANIZATION_SLUG', 'your-org-slug')
pipeline_slug = os.environ.get('BUILDKITE_PIPELINE_SLUG', 'your-pipeline-slug')

if api_access_token == 'YOUR_API_ACCESS_TOKEN_HERE':
    print("Warning: Please set the BUILDKITE_API_ACCESS_TOKEN environment variable.")
    print("You can generate one at: https://buildkite.com/user/api-access-tokens")
    exit(1)

buildkite = Buildkite()
buildkite.set_access_token(api_access_token)

try:
    # Get all info about a particular organization
    org = buildkite.organizations().get_org(org_slug)
    print(f"Organization Name: {org['name']}")

    # List all running and scheduled builds for a particular pipeline
    builds = buildkite.builds().list_all_for_pipeline(
        org_slug, pipeline_slug, states=[BuildState.RUNNING, BuildState.SCHEDULED]
    )
    print(f"Found {len(builds)} running/scheduled builds for pipeline '{pipeline_slug}':")
    for build in builds:
        print(f"  Build #{build['number']}: {build['state']} - {build['message']}")

    # Example: Create a new build (uncomment and modify to use)
    # new_build = buildkite.builds().create_build(
    #     org_slug, pipeline_slug, 'HEAD', 'main', 
    #     clean_checkout=True, message="Triggered from pybuildkite quickstart!"
    # )
    # print(f"Created new build #{new_build['number']} in pipeline '{pipeline_slug}'.")

except Exception as e:
    print(f"An error occurred: {e}")