Demo Community Plugins

This guide demonstrates how to add a Backstage community plugin to your instance and integrate it into an entity page. We use the GitHub Actions community plugin as an example and walk through:

Locating the plugin in the Backstage community repository
Installing frontend and backend packages
Registering a backend provider for authentication
Adding the plugin’s UI to an entity page
Annotating a component so the plugin can surface CI/CD data

Finding the plugin

Community plugins are discoverable on the Backstage Plugins page and in the Backstage repository on GitHub. Searching for “GitHub Actions” leads you to the plugin folder and README in the backstage/backstage/plugins area. Community plugins may include both frontend and backend packages (e.g., plugin-name and plugin-name-backend) or only frontend code. The GitHub Actions community plugin is primarily a frontend plugin but depends on backend auth/proxy support to perform authenticated requests.

A screenshot of a GitHub repository file view showing a folder tree on the left and a list of files (including README.md, package.json, CHANGELOG.md) on the right for a "GitHub Actions Plugin" workspace. The README content for the plugin is visible in the lower right.

Frontend-only plugins and backend proxies

Many frontend-only community plugins require a backend to handle authentication, hide API tokens, or proxy requests. For example, the Dynatrace plugin is a frontend app that uses a backend proxy to add API tokens server-side so tokens are never exposed in the browser. Example: adding a Dynatrace tab to an entity (JSX):

// packages/app/src/components/catalog/EntityPage.tsx (example)
const serviceEntityPage = (
  <EntityLayout>
    [...]
    <EntityLayout.Route
      path="/dynatrace"
      title="Dynatrace"
      if={isDynatraceAvailable}
    >
      <DynatraceTab />
    </EntityLayout.Route>
  </EntityLayout>
);

Example proxy configuration (YAML) that forwards requests from the frontend to a backend proxy at /dynatrace, which adds the Authorization header using a backend environment variable:

proxy:
  endpoints:
    '/dynatrace':
      target: 'https://example.dynatrace.com/api/v2'
      headers:
        Authorization: 'Api-Token ${DYNATRACE_ACCESS_TOKEN}'

dynatrace:
  baseUrl: 'https://example.dynatrace.com'

Installing the GitHub Actions plugin (frontend)

Install the frontend package inside your packages/app workspace:

# From your Backstage root directory
yarn --cwd packages/app add @backstage-community/plugin-github-actions

This adds @backstage-community/plugin-github-actions to packages/app/package.json so the frontend can import the plugin components. Example dependency excerpt from packages/app/package.json:

"dependencies": {
  "@backstage-community/plugin-github-actions": "^0.8.0",
  "@backstage/app-defaults": "^1.5.16",
  "@backstage/catalog-model": "^1.7.3",
  "@backstage/cli": "^0.29.5",
  "@backstage/core-app-api": "^1.15.4",
  "@backstage/core-components": "^0.16.3",
  "@backstage/core-plugin-api": "^1.10.3"
}

After installation, the plugin components are available under @backstage-community/plugin-github-actions.

Quick commands and files

Action	Command / File
Install frontend plugin	`yarn --cwd packages/app add @backstage-community/plugin-github-actions`
Install backend auth provider	`yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider`
Frontend entity page	`packages/app/src/components/catalog/EntityPage.tsx`
Backend entrypoint	`packages/backend/src/index.ts`

Back to the UI: the catalog and the entity page

Open your Backstage instance and navigate to the Software Catalog. Select a component (for example, “My Demo app”). Components include the Overview, CI/CD, Kubernetes, and other tabs. The GitHub Actions plugin renders CI/CD details on the CI/CD tab once configured.

A screenshot of the Backstage "My Company Catalog" web UI showing a searchable table of components (app1, app2, auth-service, etc.) with columns for owner, type, lifecycle, description and actions. A left sidebar shows navigation and filter options like Home, APIs, Docs and component kind/type.

Open the component page and check tabs and relations. This entity page is where you will add the GitHub Actions tab.

A screenshot of the Backstage software catalog page for a component named "my-demo-app," showing the Overview tab with About and Relations panels and a warning about an entity relation not found. The left navigation, top header (owner: user:guest, lifecycle: experimental), and a small relations graph are also visible.

What the plugin shows

The GitHub Actions plugin queries workflow runs for the repository referenced by the component annotation. It displays recent runs, statuses, commit messages, and links to run details on GitHub—mirroring the information on a repository’s Actions page.

A screenshot of a GitHub repository's Actions page showing a list of recent workflow runs (e.g., "Update catalog-info.yaml", "Create test.yaml") with status icons, branch labels, and timestamps. The left sidebar shows the Actions navigation menu.

If an entity is missing CI/CD annotations, the CI/CD tab will show an empty state prompting you to add the required annotation.

A screenshot of the Backstage UI for a component called "my-demo-app," showing the CI/CD tab with the message "No CI/CD available for this entity" and a "Read more" button. The left sidebar displays navigation items (Home, APIs, Docs, Create, Register) and decorative chart graphics appear on the right.

Adding the plugin UI to an entity page

Import the plugin components and add a route to your entity layout. Edit packages/app/src/components/catalog/EntityPage.tsx and insert the GitHub Actions route:

// In packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityGithubActionsContent,
  isGithubActionsAvailable,
} from '@backstage-community/plugin-github-actions';

// Example: add a GitHub Actions tab to the service entity page
const serviceEntityPage = (
  <EntityLayout>
    {/* other tabs... */}
    <EntityLayout.Route
      path="/github-actions"
      title="GitHub Actions"
      if={isGithubActionsAvailable}
    >
      <EntityGithubActionsContent />
    </EntityLayout.Route>
  </EntityLayout>
);

The plugin exports an availability helper (isGithubActionsAvailable) to conditionally render the tab only for entities that include the required annotations. You can also combine multiple CI/CD providers using EntitySwitch to show the correct provider or an empty state:

// packages/app/src/components/catalog/EntityPage.tsx (excerpt)
import { EntitySwitch } from '@backstage/plugin-catalog-react';
import { EntityGithubActionsContent, isGithubActionsAvailable } from '@backstage-community/plugin-github-actions';

const cicdContent = (
  <EntitySwitch>
    <EntitySwitch.Case if={isGithubActionsAvailable}>
      <EntityGithubActionsContent />
    </EntitySwitch.Case>

    <EntitySwitch.Case>
      <EmptyState
        title="No CI/CD available for this entity"
        missing="info"
        description="You need to add an annotation to your component if you want CI/CD information to appear."
      />
    </EntitySwitch.Case>
  </EntitySwitch>
);

Handling authentication on the backend

Although the GitHub Actions plugin runs in the frontend, it requires authenticated GitHub API requests. Backstage handles OAuth and tokens on the backend using auth modules such as @backstage/plugin-auth-backend-module-github-provider. Install the GitHub auth provider into your backend workspace:

# From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider

This will add the module to packages/backend/package.json dependencies:

"dependencies": {
  "@backstage/plugin-auth-backend": "^0.24.2",
  "@backstage/plugin-auth-backend-module-github-provider": "^0.3.0",
  "@backstage/plugin-auth-backend-module-guest-provider": "^0.2.4"
}

// packages/backend/src/index.ts (excerpt)
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

backend.add(import('@backstage/plugin-app-backend'));
backend.add(import('@backstage/plugin-proxy-backend'));
backend.add(import('@backstage/plugin-scaffolder-backend'));
// ...
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));

// other backend plugins...
backend.start();

After installing a backend package, you must both add it to packages/backend/package.json and register it in the backend index.ts with backend.add(...), then restart your backend.

Configuring GitHub OAuth and Backstage auth

Create a GitHub OAuth App under GitHub → Settings → Developer settings → OAuth Apps. Set the callback URL to Backstage’s OAuth handler, for local development: http://localhost:7007/api/auth/github/handler/frame Add the client ID and client secret to your Backstage configuration. For development you can add them to app-config.yaml; for production use environment variables or a secrets store. Example auth section in app-config.yaml:

auth:
  providers:
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
    guest: {}

After creating the OAuth app GitHub presents a client ID and lets you generate a client secret. Store these securely.

Do not commit OAuth client secrets to your repository. Use environment variables or a secrets manager (AUTH_GITHUB_CLIENT_ID, AUTH_GITHUB_CLIENT_SECRET) for production deployments.

Annotate your component with the repository project slug

To map a Backstage component to a GitHub repository, add the github.com/project-slug annotation to the component’s catalog-info.yaml. The slug is typically owner/repo (for example, backstage/backstage). Example catalog-info.yaml excerpt:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: backstage
  description: backstage.io
  annotations:
    github.com/project-slug: 'backstage/backstage'
spec:
  type: website
  lifecycle: production
  owner: user:guest

Commit and push the updated catalog-info.yaml. Backstage will refresh the entity and, if correctly configured, the GitHub Actions tab will appear and show workflow runs for the annotated repository. You can find the repository slug on the GitHub repo page.

A screenshot of a GitHub repository page for a demo app, showing a list of folders and files (e.g., .github/workflows, src, tests, package.json) in the main pane and repo details and language/activity stats in the right sidebar. The top navigation (Code, Issues, Pull requests, etc.) is also visible.

Using the plugin in Backstage

When you visit the component’s CI/CD tab, the plugin will trigger an authentication prompt handled by the backend provider. After authorizing with GitHub, the plugin will list workflow runs and provide links to the GitHub run detail pages and step logs. The experience mirrors what you get in GitHub Actions but embedded inside Backstage.

A screenshot of a GitHub Actions workflow run page showing a successful "test" job. The dark log pane lists steps like "Set up job", "Checkout code", "Setup Node.js" and "Post Setup Node.js".

Key takeaways

Community plugins may be frontend-only or include backend parts. The repository structure clarifies which is which.
Frontend plugins are installed into packages/app; backend plugins and auth modules go in packages/backend.
- Example: yarn --cwd packages/app add @backstage-community/plugin-github-actions
- Example: yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-github-provider
Backend modules must be registered with backend.add(import('...')) in packages/backend/src/index.ts and require a backend restart.
Many frontend plugins rely on backend auth modules or proxies to keep API tokens secret.
Annotate components with github.com/project-slug: 'owner/repo' to enable CI/CD data for that entity.

Plugins can render in multiple ways:

A full-page plugin (own route)
A tab inside an entity page (like CI/CD)
A small card or block on an entity page

Explore the community plugins repository and each plugin’s README for provider-specific setup instructions.

A screenshot of the Backstage Documentation page showing a list of two services (recommendation-service and shopping-cart) with a left navigation menu, search bar, and filters.

Links and references

Backstage plugins: https://backstage.io/plugins
Backstage community plugins repository: https://github.com/backstage/backstage/tree/master/plugins
Backstage authentication docs: https://backstage.io/docs/auth
GitHub OAuth apps: https://github.com/settings/developers

For further customization, consult the specific community plugin README and Backstage developer documentation.

Introduction

Backstage Basics

Catalog

Templates

TechDocs & Search

Customization & Plugins

Production Backstage

Demo Community Plugins

Finding the plugin

Frontend-only plugins and backend proxies

Installing the GitHub Actions plugin (frontend)

Quick commands and files

Back to the UI: the catalog and the entity page

What the plugin shows

Adding the plugin UI to an entity page

Handling authentication on the backend

Configuring GitHub OAuth and Backstage auth

Annotate your component with the repository project slug

Using the plugin in Backstage

Key takeaways

Links and references

Watch Video

​Finding the plugin

​Frontend-only plugins and backend proxies

​Installing the GitHub Actions plugin (frontend)

​Quick commands and files

​Back to the UI: the catalog and the entity page

​What the plugin shows

​Adding the plugin UI to an entity page

​Handling authentication on the backend

​Configuring GitHub OAuth and Backstage auth

​Annotate your component with the repository project slug

​Using the plugin in Backstage

​Key takeaways

​Links and references

Watch Video

Finding the plugin

Frontend-only plugins and backend proxies

Installing the GitHub Actions plugin (frontend)

Quick commands and files

Back to the UI: the catalog and the entity page

What the plugin shows

Adding the plugin UI to an entity page

Handling authentication on the backend

Configuring GitHub OAuth and Backstage auth

Annotate your component with the repository project slug

Using the plugin in Backstage

Key takeaways

Links and references