Backstage CircleCI Plugin

CircleCI is a continuous integration and delivery platform that builds, tests, and ships code from your repos. It connects to providers like GitHub and Bitbucket and runs workflows on every change. You get fast feedback on commits, clear build logs, and controls to promote releases. Learn more at the CircleCI website.

The CircleCI Backstage plugin brings that build signal into your service catalog. On an entity page you can see recent builds for the mapped project with status, duration, branch, commit, and who triggered them. You can open a build to inspect steps and logs without leaving Backstage. When a job flakes out you can kick off a retry from the same view. Pagination and light polling make it practical to browse history and follow live output. Links take you to the CircleCI UI when you need deeper context.

Common uses include watching pipeline health during a deploy, triaging failures where your team works, and giving a shared view of build status across many services. It helps cut context switching and makes CI part of your internal developer portal.

There are a few things to keep in mind. CircleCI rate limits apply to the token you use, so many open tabs can hit limits. Auth goes through CircleCI tokens rather than third party SSO. Plan token scope and rotation as part of your setup.

Installation Instructions

These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.

Install the frontend package in your Backstage app

Copy

yarn add --cwd packages/app @circleci/backstage-plugin

Add the CircleCI content to the entity page

Copy

// packages/app/src/components/catalog/EntityPage.tsx

import React from 'react';
import { EntitySwitch } from '@backstage/plugin-catalog';
import {
  EntityCircleCIContent,
  isCircleCIAvailable,
} from '@circleci/backstage-plugin';

// find your CI CD content section or create one
const cicdContent = (
  <EntitySwitch>
    <EntitySwitch.Case if={isCircleCIAvailable}>
      <EntityCircleCIContent />
    </EntitySwitch.Case>
  </EntitySwitch>
);

// make sure cicdContent is rendered on your EntityPage
// for example
// const serviceEntityPage = (
//   <EntityLayout>
//     <EntityLayout.Route path="/ci-cd" title="CI CD">
//       {cicdContent}
//     </EntityLayout.Route>
//   </EntityLayout>
// );

Add the proxy configuration so the frontend can call CircleCI through the Backstage backend

Copy

# app-config.yaml
proxy:
  '/circleci/api':
    target: https://circleci.com/api/v1.1
    headers:
      Circle-Token: ${CIRCLECI_AUTH_TOKEN}

Provide the CircleCI token at runtime. Use a CircleCI personal API token or a project API token

Copy

# example for local dev
CIRCLECI_AUTH_TOKEN=your_circleci_token yarn dev

Annotate your catalog entities so the plugin knows which CircleCI project to use

Copy

# example catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  annotations:
    circleci.com/project-slug: github/my-org/my-repo
spec:
  type: service
  lifecycle: production
  owner: team-a

Enable the proxy backend in the new backend system

Copy

yarn add --cwd packages/backend @backstage/plugin-proxy-backend

Copy

// packages/backend/src/index.ts

import { createBackend } from '@backstage/backend-defaults';
import { proxy } from '@backstage/plugin-proxy-backend';

const backend = createBackend();

// register the proxy backend plugin
backend.add(proxy());

backend.start();

Enable the proxy backend in the old backend system

Copy

yarn add --cwd packages/backend @backstage/plugin-proxy-backend

Copy

// packages/backend/src/plugins/proxy.ts

import { createRouter } from '@backstage/plugin-proxy-backend';
import { PluginEnvironment } from '../types';
import { Router } from 'express';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  return await createRouter({
    logger: env.logger,
    config: env.config,
    discovery: env.discovery,
    tokenManager: env.tokenManager,
    httpAuth: env.httpAuth,
  });
}

Copy

// packages/backend/src/index.ts

import proxy from './plugins/proxy';

// inside your main bootstrap where you add plugin routers
// example with an express router named apiRouter
apiRouter.use('/proxy', await proxy(env));

What you should see in the app after these steps

A CI CD tab or route on the entity page that renders the CircleCI builds for the annotated entity
The plugin lists recent builds
You can open a build to see details and logs
You can retry a build when allowed by your token permissions

Changelog

This changelog is produced from commits made to the CircleCI plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

Remove the output page from the plugin. This breaks any route or link to that page #10 merged 11 months ago

Maintenance

Update dependencies #10 merged 11 months ago

Installation Instructions

Changelog

Breaking changes

Maintenance

Set up Backstage in minutes with Roadie