{"id":2211,"library":"pybuildkite","title":"pybuildkite","description":"pybuildkite is a Python wrapper library for interacting with the Buildkite CI/CD platform's REST API. It provides a programmatic interface to manage organizations, pipelines, builds, agents, and other Buildkite resources. The library is currently at version 1.3.0 and mirrors the functionality of the Buildkite API, which is primarily a REST API (currently v2). Its release cadence is driven by updates to the underlying Buildkite API and community contributions.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/pyasi/pybuildkite.git","tags":["buildkite","ci-cd","api-wrapper","automation"],"install":[{"cmd":"pip install pybuildkite","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The class name is 'Buildkite' (lowercase 'k'). Using 'BuildKite' (uppercase 'K') will result in an ImportError or NameError.","wrong":"from pybuildkite.buildkite import BuildKite","symbol":"Buildkite","correct":"from pybuildkite.buildkite import Buildkite"},{"note":"Used for filtering builds by their state (e.g., RUNNING, SCHEDULED).","symbol":"BuildState","correct":"from pybuildkite.buildkite import BuildState"}],"quickstart":{"code":"import os\nfrom pybuildkite.buildkite import Buildkite, BuildState\n\n# Get your Buildkite API access token from environment variables\napi_access_token = os.environ.get('BUILDKITE_API_ACCESS_TOKEN', 'YOUR_API_ACCESS_TOKEN_HERE')\norg_slug = os.environ.get('BUILDKITE_ORGANIZATION_SLUG', 'your-org-slug')\npipeline_slug = os.environ.get('BUILDKITE_PIPELINE_SLUG', 'your-pipeline-slug')\n\nif api_access_token == 'YOUR_API_ACCESS_TOKEN_HERE':\n    print(\"Warning: Please set the BUILDKITE_API_ACCESS_TOKEN environment variable.\")\n    print(\"You can generate one at: https://buildkite.com/user/api-access-tokens\")\n    exit(1)\n\nbuildkite = Buildkite()\nbuildkite.set_access_token(api_access_token)\n\ntry:\n    # Get all info about a particular organization\n    org = buildkite.organizations().get_org(org_slug)\n    print(f\"Organization Name: {org['name']}\")\n\n    # List all running and scheduled builds for a particular pipeline\n    builds = buildkite.builds().list_all_for_pipeline(\n        org_slug, pipeline_slug, states=[BuildState.RUNNING, BuildState.SCHEDULED]\n    )\n    print(f\"Found {len(builds)} running/scheduled builds for pipeline '{pipeline_slug}':\")\n    for build in builds:\n        print(f\"  Build #{build['number']}: {build['state']} - {build['message']}\")\n\n    # Example: Create a new build (uncomment and modify to use)\n    # new_build = buildkite.builds().create_build(\n    #     org_slug, pipeline_slug, 'HEAD', 'main', \n    #     clean_checkout=True, message=\"Triggered from pybuildkite quickstart!\"\n    # )\n    # print(f\"Created new build #{new_build['number']} in pipeline '{pipeline_slug}'.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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).","severity":"breaking","affected_versions":"<1.0.0 (potentially)"},{"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: ...`","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (user responsibility)"},{"fix":"Ensure correct capitalization when importing: `from pybuildkite.buildkite import Buildkite`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}