Backstage Plugin

Getting Started

Before setting up your Backstage Plugin, you'll need to first install our Github App. By default, we'll generate CODEOWNERS files for you - at your request we can disable this functionality, please reach out to support.

Backstage Configuration

You'll need to configure a proxy to CODEOWNERS.com and place the CODEOWNERS.com cards in your catalog entity pages.

Create a CODEOWNERS.com Personal Access Token

See documentation for creating your personal access token.

Configure API Proxy

Configure Backstage so that the Codeowners plugin can communicate to the codeowners.com API:

# in app-config.yaml
proxy:
  '/codeowners/api':
    target: https://api.codeowners.com/api/v1
    headers:
      Authorization: Bearer ${CODEOWNERS_API_KEY}

Reminder: Be sure to create CODEOWNERS_API_KEY environment variable where you run your Backstage server.

Add the CODEOWNERS.com Settings Page

1. Add a route to the Codeowners settings page:

// packages/app/src/App.tsx
import { CodeownersSettingsPage } from "@codeowners/backstage-plugin";

const routes = (
  <FlatRoutes>
    {/* snip... */}
    <Route path="/codeowners" element={<CodeownersSettingsPage />} />
  </FlatRoutes>
);

2. Create a link in the Backstage sidebar to the Codeowners settings page

// packages/app/src/components/Root/Root.tsx
import { CodeownersIcon } from "@codeowners/backstage-plugin";

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
      {/* snip...  */}
      <SidebarItem icon={CodeownersIcon} to="codeowners" text="CODEOWNERS.com" />
    </Sidebar>
  </SidebarPage>
);

Add the CODEOWNERS.com Backstage plugin cards

1. Add the CODEOWNERS.com module to your Backstage instance:

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

2. Import the cards you want to use in the Backstage entity overview page:

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

 // Add the following in the imports
 import { ServiceCodeownersCard, RecentChangesCard } from "@codeowners/backstage-plugin";

3. In the same file, look for the overviewContent object and add the cards you want to use in its Grid:

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {entityWarningContent}
    { /*  snip other cards... */ }
    <Grid item xs={4}>
      <ServiceCodeownersCard />
    </Grid>
    <Grid item xs={8}>
      <RecentChangesCard />
    </Grid>
  </Grid>
);