@buildkite/backstage-plugin-buildkite

Buildkite Backstage Plugin

A Buildkite plugin for Backstage that provides deep integration with your Buildkite CI/CD pipelines.

✨ Features

🔍 Enhanced Pipeline Visibility

• Real-time build status monitoring with automatic updates
• Hierarchical branch-based organization of builds
• Detailed step-by-step build progress tracking
• Comprehensive build logs with syntax highlighting

⚡️ Powerful Filtering & Search

• Full-text search across builds, messages, authors, branches, and commit IDs
• Smart date range filtering with preset options (Today, Yesterday, Last 7 days, Last 30 days)
• Multi-criteria filtering by branch, creator, and build status
• Automatic status-based grouping and organization

📊 Rich Build Information

• Detailed build status with step-by-step progress
• Build timing and duration tracking
• Commit and branch context
• Author information with avatars
• Build trigger information

🛠️ Interactive Build Management

• One-click rebuild functionality
• Expandable/collapsible build details
• Interactive build step inspection
• Direct links to Buildkite

⚙️ Advanced Customization

• UTC/Local time toggle with persistent preferences
• Branch-level collapsing
• Automatic expansion of running builds
• Custom pipeline styling with avatars

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

• 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']

buildkite:
  apiToken: ${BUILDKITE_API_TOKEN}
  organization: ${BUILDKITE_ORGANIZATION}

• Create or update packages/app/src/plugins.ts to register the plugin:

// Import plugins that you want to be included in your app
export { buildkitePlugin } from '@buildkite/backstage-plugin-buildkite';

• Make sure to import the plugins file in your packages/app/src/App.tsx:

// Import plugins
import './plugins';

• Add the API factory in packages/app/src/apis.ts:

import { buildkiteAPIRef, BuildkiteClient } from '@buildkite/backstage-plugin-buildkite';

export const apis: AnyApiFactory[] = [
  createApiFactory({
    api: buildkiteAPIRef,
    deps: { discoveryApi: discoveryApiRef, fetchApi: fetchApiRef, configApi: configApiRef },
    factory: ({ discoveryApi, fetchApi, configApi }) => {
      const buildkiteConfig = configApi.getOptionalConfig('buildkite');
      return new BuildkiteClient({
        discoveryAPI: discoveryApi,
        fetchAPI: fetchApi,
        config: {
          organization: buildkiteConfig?.getOptionalString('organization') ?? 'default-org',
          defaultPageSize: buildkiteConfig?.getOptionalNumber('defaultPageSize') ?? 25,
          apiBaseUrl: buildkiteConfig?.getOptionalString('apiBaseUrl') ?? 'https://api.buildkite.com/v2',
        },
      });
    },
  }),
];

• 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>
);

• 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

Development

# Install dependencies
yarn install

# Start plugin in development mode
yarn start

# Run tests
yarn test

# Build plugin
yarn build

Tracking Deployments

The plugin can track deployments across your Buildkite pipelines. There are three ways to mark a build as a deployment:

1. Using the environment metadata field

Set the environment metadata field in your Buildkite build using the buildkite-agent command:

# In your pipeline.yml
steps:
  - label: "Deploy to Production"
    command: |
      buildkite-agent meta-data set "environment" "production"
      ./scripts/deploy.sh

2. Using the app:environment:deployed pattern

For deployments where you want to track both the application name and environment:

# In your pipeline.yml
steps:
  - label: "Deploy Frontend to Staging"
    command: |
      buildkite-agent meta-data set "frontend:staging:deployed" "true"
      ./scripts/deploy-frontend-staging.sh
    branches: "main"

  - label: "Deploy Backend to Staging"
    command: |
      buildkite-agent meta-data set "backend:staging:deployed" "true"
      ./scripts/deploy-backend-staging.sh
    branches: "main"

This format allows you to track multiple applications deployed to different environments and will display both the application name and environment in the deployments view.

3. Using environment-specific deployment flags

For pipelines that deploy to multiple environments sequentially (e.g., staging then production), you can use environment-specific flags:

# In your pipeline.yml
steps:
  - label: "Deploy to Staging"
    command: |
      buildkite-agent meta-data set "staging_deployment" "true"
      ./scripts/deploy-staging.sh
    branches: "main"

  - block: "Promote to Production?"
    branches: "main"

  - label: "Deploy to Production"
    command: |
      buildkite-agent meta-data set "production_deployment" "true"
      ./scripts/deploy-production.sh
    branches: "main"

This allows tracking multiple deployments from a single build as they progress through your environments.

Troubleshooting

Common Issues

• Authentication Errors

  • Verify BUILDKITE_API_TOKEN is set in your environment
  • Check API token has required permissions
  • Confirm proxy configuration in app-config.yaml

• Missing Build Data

  • Verify pipeline slug format: organization-slug/pipeline-slug
  • Check organization and pipeline names are correct
  • Ensure builds exist within selected date range
  • Confirm all filters are set correctly

• Real-time Updates Not Working

  • Check browser tab is active (updates pause in background)
  • Verify network connectivity
  • Ensure API token hasn't expired

• Build Logs Not Loading

  • Confirm API token has read_builds permission
  • Check build exists and is accessible
  • Verify proxy configuration can handle log requests

Contributing

Please read our Contributing Guide before submitting a Pull Request.