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.
Installation Instructions
These instructions apply to self-hosted Backstage only.
Install the frontend package
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.
// 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.
// 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.
// 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.
// 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.
# 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.
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.
# 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.
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.
// 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, 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
- 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.