CodeScene helps you understand how your code evolves in real life. It connects code with people and product goals. It spots risk hot spots and patterns in change. It gives you a practical way to focus refactoring work and reduce technical debt.
The CodeScene Backstage plugin brings those insights into your developer portal. It adds a page that lists the projects in your CodeScene instance with their latest analysis. You can open a project to see details. You can surface key metrics on each service page with cards for KPIs and file level summaries. That means engineers can check code health as part of their normal workflow. The plugin was introduced by the Backstage community as a way to view CodeScene data inside Backstage.
Typical use cases fit everyday work. Track hot spots across services during planning. Review risky files before a release. Watch trends in code health over time to guide cleanup. Bring shared visibility to teams and tech leads without leaving Backstage. If your org already runs CodeScene, the plugin lets you use that investment where engineers spend time.
Installation Instructions
These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.
Install the package
yarn --cwd packages/app add @backstage-community/plugin-codesceneAdd top level routes
Edit packages/app/src/App.tsx. Import the pages. Add two routes.
// packages/app/src/App.tsx
import React from 'react';
import { Route } from 'react-router-dom';
import {
CodeScenePage,
CodeSceneProjectDetailsPage,
} from '@backstage-community/plugin-codescene';
// inside your Routes block
<Route path="/codescene" element={<CodeScenePage />} />
<Route path="/codescene/:projectId" element={<CodeSceneProjectDetailsPage />} />Add a sidebar link
Edit packages/app/src/components/Root/Root.tsx. Import the icon. Add a sidebar item that points to the new page.
// packages/app/src/components/Root/Root.tsx
import React from 'react';
import { SidebarItem } from '@backstage/core-components';
import { CodeSceneIcon } from '@backstage-community/plugin-codescene';
// inside your Sidebar group
<SidebarItem icon={CodeSceneIcon} to="codescene" text="CodeScene" />Configure the proxy
Add a proxy route in app-config.yaml. The UI calls this path. The backend proxy forwards it to your CodeScene instance.
# app-config.yaml
proxy:
'/codescene-api':
target: '<INSTANCE_HOSTNAME>/api/v1'
allowedMethods: ['GET']
allowedHeaders: ['Authorization']
headers:
Authorization: Basic ${CODESCENE_AUTH_CREDENTIALS}Set CODESCENE_AUTH_CREDENTIALS in your runtime environment. Use a value that matches your CodeScene auth policy.
Configure the CodeScene base URL
Add the base URL so the plugin can link out to CodeScene.
# app-config.yaml
codescene:
baseUrl: https://codescene.my-company.netAnnotate catalog entities
Add the project id to each entity that should show CodeScene data.
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: backstage
annotations:
codescene.io/project-id: <codescene-project-id>
spec:
type: service
owner: team-a
lifecycle: productionAdd CodeScene cards to the Entity page
Edit packages/app/src/components/catalog/EntityPage.tsx. Import the components. Add a new Entity tab with two cards.
// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import Grid from '@material-ui/core/Grid';
import { EntityLayout } from '@backstage/plugin-catalog';
import {
CodeSceneEntityKPICard,
CodeSceneEntityFileSummary,
isCodeSceneAvailable,
} from '@backstage-community/plugin-codescene';
// inside your EntityLayout
<EntityLayout.Route path="/codescene" title="CodeScene" if={isCodeSceneAvailable}>
<Grid container spacing={3} alignItems="stretch">
<Grid item md={6} xs={12}>
<CodeSceneEntityKPICard />
</Grid>
<Grid item md={6} xs={12}>
<CodeSceneEntityFileSummary />
</Grid>
</Grid>
</EntityLayout.Route>Changelog
This changelog is produced from commits made to the CodeScene 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.
Set up Backstage in minutes with Roadie
Focus on using Backstage, rather than building and maintaining it.