Backstage FOSSA Plugin

FOSSA helps teams understand the open source in their code. It scans dependencies, flags license issues, and supports policy driven workflows and reports. It fits into CI and daily review so you can fix problems early.

The FOSSA Backstage plugin brings that context into your developer portal. It shows license status for each component in your catalog so engineers see risk where they work. You can add a project card to a service page for a quick read on issues. You can add an overview page to track compliance across many services and jump straight to the FOSSA project for detail. The goal is simple. Keep release work moving while keeping legal risk in view.

Typical use cases include release readiness checks before a tag or deploy. Fleet views to spot policy violations by team or system. Faster triage when a new library lands with a license your rules do not allow. Clear links back to FOSSA for remediation steps and reports.

If you already use Backstage to show build, runtime, and docs, this plugin fills the license gap. It reduces window switching and keeps decisions close to the code. It is a small change for engineers. It is a big step for consistent compliance across your catalog.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend package

Copy

yarn --cwd packages/app add @backstage-community/plugin-fossa

Add the FOSSA card to your entity page

Add the card so users see FOSSA data on each service page.

Copy

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

import React from 'react';
import Grid from '@material-ui/core/Grid';
import { Entity } from '@backstage/catalog-model';
import { EntityFossaCard } from '@backstage-community/plugin-fossa';

const OverviewContent = ({ entity }: { entity: Entity }) => (
  <Grid container spacing={3} alignItems="stretch">
    {/* other cards */}
    <Grid item xs={12} sm={6} md={4}>
      <EntityFossaCard />
    </Grid>
    {/* other cards */}
  </Grid>
);

// keep the rest of your EntityPage setup as is

Add the optional FOSSA overview page

This page lists FOSSA status across catalog entities.

Copy

// packages/app/src/App.tsx

import React from 'react';
import { FlatRoutes } from '@backstage/core-app-api';
import { Route } from 'react-router';
import { FossaPage } from '@backstage-community/plugin-fossa';

// inside your routes
export const routes = (
  <FlatRoutes>
    {/* other routes */}
    <Route path="/fossa" element={<FossaPage />} />
  </FlatRoutes>
);

Add a sidebar item so users can reach the page.

Copy

// packages/app/src/components/Root/Root.tsx

import React, { PropsWithChildren } from 'react';
import { SidebarPage, Sidebar, SidebarItem } from '@backstage/core-components';
import CheckCircleIcon from '@material-ui/icons/CheckCircle';

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
      {/* other items */}
      <SidebarItem icon={CheckCircleIcon} to="fossa" text="FOSSA" />
      {/* other items */}
    </Sidebar>
    {children}
  </SidebarPage>
);

Configure the proxy and plugin settings

Add a proxy route that forwards calls to FOSSA. Add optional FOSSA settings.

Copy

# app-config.yaml

proxy:
  '/fossa':
    target: https://app.fossa.io/api
    allowedMethods: ['GET']
    headers:
      Authorization: token ${FOSSA_API_TOKEN}

fossa:
  # set your FOSSA organization id if you have one
  organizationId: <your-fossa-organization-id>
  # set this if you use a self managed FOSSA instance
  externalLinkBaseUrl: <your-fossa-url>

Set the token as an environment variable.

Copy

# dev shell
export FOSSA_API_TOKEN=your_token_here

Enable the proxy on the backend

The proxy backend must be running. Many Backstage apps already include it. If you do not see it, add it using one of the setups below.

New backend system

Copy

// packages/backend/src/index.ts

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

const backend = createBackend();

// other plugins
backend.add(import('@backstage/plugin-proxy-backend'));

backend.start();

Old backend system

Create the proxy plugin module.

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,
  });
}

Wire it up in the backend.

Copy

// packages/backend/src/index.ts

import proxy from './plugins/proxy';

// inside main bootstrap
const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
apiRouter.use('/proxy', await proxy(proxyEnv));

Make sure your backend reads the same app config with the proxy section shown above.

Annotate your catalog entities

Add the FOSSA project name to each entity that should show FOSSA data.

Copy

# catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: backstage
  annotations:
    fossa.io/project-name: YOUR_PROJECT_NAME
spec:
  type: library
  owner: your-owner
  lifecycle: production

Get a FOSSA API token

Create a token in your FOSSA account settings. Set it in the environment variable shown above.

Things to Know

The FOSSA plugin is a frontend plugin that summarizes license findings for components in Backstage. The plugin includes a card component that displays a summary of findings for individual components:

FOSSA Card Component

It also includes a page component that displays a summary of findings for all components in Backstage that are annotated with the FOSSA plugin annotation:

FOSSA Page Component

Both components allow users to link directly to findings on the FOSSA website.

Creating a FOSSA API key

A FOSSA API key is required for Backstage to connect to the FOSSA API to retrieve license findings. FOSSA API keys are associated with to FOSSA user accounts.

To create a FOSSA API key:

Open app.fossa.com/account/settings.
Navigate to the API section on the Integrations tab.
Add a new token. Do not select the “Push Only” option.
Copy the token and save it to FOSSA_API_TOKEN environment variable.

Specifying a FOSSA organization ID

You can optionally provide a FOSSA organization ID in app-config.yaml:

Copy

fossa:
  organizationId: <your-fossa-organization-id>

Organization ID is not currently required by the functionality included with this plugin. FOSSA findings are retrieved using the fossa.io/project-name (FOSSA project title) in the component’s catalog-info.yml. If an organization ID is provided, it is added as an additional filter parameter on the FOSSA API request to retrieve project details but it ultimately will not affect the data that is returned.

Changelog

This changelog is produced from commits made to the FOSSA 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.

Dependencies

Remove unused dev dependency canvas #3565 merged 5 months ago

Maintenance

Update repo tools to 0.13.0 to reduce knip false positives in workspace reports #3018 merged 6 months ago

Set up Backstage in minutes with Roadie

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

Get a demo