Buildkite Backstage Plugin

A Buildkite plugin for Backstage that provides deep integration with your Buildkite CI/CD pipelines. This plugin allows you to monitor the status of your pipelines and manage their builds from a single interface.

Prerequisites

• Buildkite account with API access
• Required API token permissions:
  • read_pipelines
  • read_builds
  • read_user
  • write_builds (for rebuild functionality)

Installation

Plugin Installation

If the plugin is in your project's plugins directory:

yarn workspace app add @buildkite/backstage-plugin-buildkite

If you're installing from an external package:

yarn workspace app add @buildkite/backstage-plugin-buildkite

Configuration

1. Add the proxy configuration to your app-config.yaml:

proxy:
  endpoints:
    '/buildkite/api':
      target: https://api.buildkite.com/v2
      headers:
        Authorization: Bearer ${BUILDKITE_API_TOKEN}
        Accept: application/json
      allowedHeaders: ['Authorization']

Note: The plugin uses the Backstage proxy for authentication. The organization and pipeline are specified per-entity via annotations (see Component Configuration below).

Optional configuration can be added to app-config.yaml:

buildkite:
  # Optional: Override the API base URL (default: https://api.buildkite.com/v2)
  apiBaseUrl: https://api.buildkite.com/v2
  # Optional: Set default page size for pagination (default: 25)
  defaultPageSize: 25

2. Add routes in packages/app/src/App.tsx:

import { PipelinePage } from '@buildkite/backstage-plugin-buildkite';

const routes = (
  <FlatRoutes>
    {/* Other routes... */}

    {/* Buildkite Plugin Routes */}
    <Route path="/buildkite" element={<PipelinePage />} />
    <Route path="/buildkite/pipeline/:orgSlug/:pipelineSlug" element={<PipelinePage />} />
  </FlatRoutes>
);

3. Add to your Entity Page in packages/app/src/components/catalog/EntityPage.tsx:

import { isBuildkiteAvailable, BuildkiteWrapper } from '@buildkite/backstage-plugin-buildkite';

const cicdContent = (
  <EntitySwitch>
    <EntitySwitch.Case if={isBuildkiteAvailable}>
      <BuildkiteWrapper />
    </EntitySwitch.Case>
    <EntitySwitch.Case>
      <EmptyState
        title="No CI/CD available for this entity"
        missing="info"
        description="Add a Buildkite annotation to enable CI/CD visualization"
      />
    </EntitySwitch.Case>
  </EntitySwitch>
);

const defaultEntityPage = (
  <EntityLayout>
    {/* Other routes... */}

    <EntityLayout.Route path="/ci-cd" title="CI/CD">
      {cicdContent}
    </EntityLayout.Route>
  </EntityLayout>
);

Component Configuration

Add the Buildkite annotation to your component's catalog-info.yaml:

metadata:
  annotations:
    buildkite.com/pipeline-slug: organization-slug/pipeline-slug

Documentation

For further usage tips for the Buildkite plugin for Backstage, as well as deployment visibility overview and troubleshooting, see the the official Buildkite Documentation:

• Plugin overview
• Deployment tracking
• Deployment visibility with Backstage

Development

For guidelines and requirements regarding contributing to the Buildkite Agent Stack for Kubernetes controller, please see the Contributing/Development Guide.