Backstage GitHub Insights Plugin

GitHub Insights surfaces repository activity and context from your GitHub org. It helps you see who contributes, what languages are used, when releases happen, and what the readme says. The GitHub Insights plugin brings this into Backstage so you can view code signals beside ownership data, docs, and runtime links.

The plugin adds a Code Insights tab on your service pages. It ships ready made cards for contributors, languages, readme, releases, environments, and compliance. You can show a quick view in the overview too. It works with GitHub Enterprise and GitHub SaaS. Typical use cases include onboarding to a repo, checking release history before a deploy, scanning contributors for the right reviewers, and reading the readme without leaving Backstage.

Some teams extend the plugin to fit their needs. For example Liatrio built an add on that displays automated governance results inside the Releases card. They describe it this way: “This will show the results under the GitHub Code Insights tab in the GitHub Releases card.” You can read more on their repo at.If you already map components to GitHub repos in your catalog, you can drop this into your Backstage app and start giving engineers useful context where they work. It reduces tab switching. It keeps code centric facts close to the rest of your developer portal.

A screenshot of the GitHub Insights plugin. It is showing a code details for a sample component.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend package

Copy

cd packages/app
yarn add @roadiehq/backstage-plugin-github-insights

Ensure SCM auth is registered

The plugin needs SCM auth in the frontend app.

Add the default SCM auth API factory.

Copy

// packages/app/src/apis.ts
import { ScmAuth } from '@backstage/integration-react';

export const apis = [
  // keep your existing api factories here
  ScmAuth.createDefaultApiFactory(),
];

If your app uses a different pattern for APIs, register the same factory in that place.

Add the GitHub insights tab to the entity page

Add the tab so users can open the full insights view.

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout, EntitySwitch } from '@backstage/plugin-catalog';
import { Grid } from '@material-ui/core';
import {
  EntityGithubInsightsContent,
} from '@roadiehq/backstage-plugin-github-insights';

// keep your existing page code

const serviceEntityPage = (
  <EntityLayout>
    {/* keep your other routes */}
    <EntityLayout.Route path="/code-insights" title="Code Insights">
      <EntityGithubInsightsContent />
    </EntityLayout.Route>
  </EntityLayout>
);

// make sure your router uses serviceEntityPage for Service entities

Add the widgets to the overview tab

You can place one widget or many.

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout, EntitySwitch } from '@backstage/plugin-catalog';
import { Grid } from '@material-ui/core';
import {
  EntityGithubInsightsLanguagesCard,
  EntityGithubInsightsReadmeCard,
  EntityGithubInsightsReleasesCard,
  isGithubInsightsAvailable,
} from '@roadiehq/backstage-plugin-github-insights';

// inside your overview content
const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    <EntitySwitch>
      <EntitySwitch.Case if={isGithubInsightsAvailable}>
        <Grid item md={6}>
          <EntityGithubInsightsLanguagesCard />
          <EntityGithubInsightsReleasesCard />
        </Grid>
        <Grid item md={6}>
          <EntityGithubInsightsReadmeCard maxHeight={350} />
        </Grid>
      </EntitySwitch.Case>
    </EntitySwitch>
  </Grid>
);

// render overviewContent inside your overview route

You can also import other widgets when needed.

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityGithubInsightsComplianceCard,
  EntityGithubInsightsContributorsCard,
  EntityGithubInsightsEnvironmentsCard,
} from '@roadiehq/backstage-plugin-github-insights';

Add required entity annotations

The plugin reads data based on the project slug. Add this to each entity that should show insights.

Copy

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

Optional custom readme path

Use this when the readme lives outside the repo root.

Copy

metadata:
  annotations:
    github.com/project-slug: my-org/my-repo
    github.com/project-readme-path: packages/sub-module/README.md

Backend setup new backend system

No backend package is required for this plugin. There is nothing to install in the new backend.

Backend setup legacy backend system

No backend package is required for this plugin. There is nothing to install in the legacy backend.

Configure GitHub integrations and auth

Add your GitHub host under integrations. Add the GitHub auth provider so users can sign in and grant scopes.

Copy

# app-config.yaml
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

auth:
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}

For GitHub Enterprise replace the host and token.

Copy

integrations:
  github:
    - host: ghe.my-company.example.com
      apiBaseUrl: https://ghe.my-company.example.com/api/v3
      rawBaseUrl: https://ghe.my-company.example.com/raw
      token: ${GHE_TOKEN}

Make sure your Sign In page includes the GitHub provider.

Copy

// packages/app/src/App.tsx
import { githubAuthApiRef } from '@backstage/core-plugin-api';
import { SignInPage } from '@backstage/core-components';

// inside your App provider tree
<SignInPage
  auto
  provider={{
    id: 'github-auth-provider',
    title: 'GitHub',
    message: 'Sign in using GitHub',
    apiRef: githubAuthApiRef,
  }}
/>

What the user will see

A Code Insights tab on the entity page
Widgets on the overview tab such as languages readme releases contributors compliance and environments

This depends on the annotations on each entity and on the user being signed in with GitHub through SCM auth.

Changelog

This changelog is produced from commits made to the GitHub Insights plugin since a year ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

Prefer SCM auth over GitHub auth in GitHub Insights. You may need to enable the SCM auth provider in your app config. Update any setups that rely only on the old GitHub auth flow. #1783 9 months ago

Features

Share GitHub auth state across plugins. GitHub Insights can show or hide parts based on scopes and target urls. #1792 9 months ago

Bug fixes

Fix Sign In button on GitHub Insights pages. Add a common login wrapper in the plugin. #1788 9 months ago
Stop the Contributors card from showing Login Required on the entity page. #1690 11 months ago

Maintenance

Upgrade to 1 40. #1952 2 months ago
Remove unused plugin dependencies. #1847 7 months ago
Revert a dependency update that caused issues. #1825 8 months ago
Update dependencies in plugins. #1821 8 months ago
Update a dependency in GitHub plugin packages. #1801 9 months ago
Update actions and scaffolder packages. #1794 9 months ago
Update Backstage package versions. #1728 10 months ago

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo