Backstage VeeCode GitHub Workflows Plugin

VeeCode GitHub Workflows is a Backstage plugin that lets your team view and trigger GitHub Actions directly inside your developer portal. It gives you a focused place in Backstage where engineers can see the workflows tied to a service and run the ones they need without leaving the page. You can surface all workflows for a repo or highlight only the ones that matter for that component.

The plugin shows the workflows for a chosen branch with current status and a quick refresh. If a workflow needs inputs, it prompts for them before running. After a run starts, you can follow progress and open details to review jobs and logs. It supports a table view for full listings as well as a cards view that spotlights key workflows in an overview. It also complements the standard GitHub Actions plugin so you can jump from triggers to run history.

Common use cases include on demand deploys, database or cache tasks, data backfills, smoke tests, or release checks. Teams can use it to speed up incident response by giving clear entry points to the actions they trust. It works with GitHub cloud and can be set up for GitHub Enterprise when your Backstage instance is configured for it. If your goal is fewer context switches, this plugin keeps routine work close to the code and the catalog.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend package

If your repo uses yarn workspaces with yarn 3

Copy

yarn workspace app add @veecode-platform/backstage-plugin-github-workflows

If your repo uses an older yarn layout

Copy

yarn add --cwd packages/app @veecode-platform/backstage-plugin-github-workflows

Configure GitHub integration in app config

Set the GitHub integration with an API base URL and a token. Add this in app config

Copy

integrations:
  github:
    - host: github.com
+     apiBaseUrl: https://api.github.com/
      token: ${GITHUB_TOKEN_SECRET}

Configure GitHub auth in app config

Add a GitHub auth provider. Example for a development profile

Copy

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

Allow GitHub avatars in the content security policy

Add the GitHub avatar host in app config

Copy

csp:
  connect-src: ["'self'", 'http:', 'https:']
  script-src: ["'self'", "'unsafe-eval'"]
+ img-src: ["'self'", 'data:','https://avatars.githubusercontent.com/']

Enable manual triggers in your GitHub workflows

Add the workflow dispatch event in each workflow you want to trigger from Backstage

Copy

# .github/workflows/example.yml
name: Deploy Next.js site to Pages

on:
  push:
    branches: ["master"]
+ workflow_dispatch:

# steps follow

Even without inputs defined the key must exist for manual triggers to work.

Add required catalog annotations

Add the project slug to each entity that should show workflows

Copy

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: example-component
  annotations:
    github.com/project-slug: owner/repo
spec:
  type: service
  owner: team
  lifecycle: production

Optional filter annotation for specific workflows by file path

Copy

metadata:
  annotations:
    github.com/workflows: filePath.yml,filePath2.yml

Optional advanced form to customize card label and tooltip

Copy

metadata:
  annotations:
    github.com/workflows: |
      [
        {
          "workflow": "fileName.yml",
          "label": "Start",
          "tooltip": "click here and start the workflow process"
        }
      ]

Add a Workflows tab to the entity page

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

Import the plugin components

Copy

import React from 'react';
import { EntityLayout, EntitySwitch } from '@backstage/plugin-catalog';
import { EmptyState } from '@backstage/core-components';
import { Button } from '@material-ui/core';
// or import { Button } from '@mui/material' if your app uses MUI v5
import {
  GithubWorkflowsContent,
  isGithubWorkflowsAvailable,
} from '@veecode-platform/backstage-plugin-github-workflows';

Add a new route under your service entity page

Copy

const serviceEntityPage = (
  <EntityLayout>
    {/* other routes */}
    <EntityLayout.Route path="workflows" title="Workflows">
      <EntitySwitch>
        <EntitySwitch.Case if={isGithubWorkflowsAvailable}>
          <GithubWorkflowsContent />
        </EntitySwitch.Case>
        <EntitySwitch.Case>
          <EmptyState
            title="No CI CD available for this entity"
            missing="info"
            description="Add the required annotation to enable workflows for this entity"
            action={
              <Button variant="contained" color="primary">
                Read more
              </Button>
            }
          />
        </EntitySwitch.Case>
      </EntitySwitch>
    </EntityLayout.Route>
  </EntityLayout>
);

Run the app. Open an entity that has the annotations. Use the Workflows tab.

Alternative add cards to the overview

You can render workflow cards on the Overview tab. The annotation github.com/workflows can filter which workflows appear. If you omit it the component lists all workflows.

Edit packages/app/src/components/catalog/EntityPage.tsx and import the same items as above. In your overview content add

Copy

<EntitySwitch>
  <EntitySwitch.Case if={isGithubWorkflowsAvailable}>
    <GithubWorkflowsContent cards />
  </EntitySwitch.Case>
</EntitySwitch>

Place it inside the grid with your Overview cards.

Backend setup for both backend systems

No backend package is required. The plugin calls the GitHub API from the frontend using your GitHub integration and auth settings. This works with the legacy backend and with the new backend system. There are no backend install steps for this plugin.

Usage notes

The component lists workflows in the repo of the annotated entity
Use the branch selector in the header to switch branches
If a workflow has required inputs the component opens a form before triggering
Use the Logs link in the list or the label in a card to view details and job logs

Changelog

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

Breaking changes

Rename entityGithubWorkflowsContent to GithubWorkflowsTabContent. Update your imports to use GithubWorkflowsTabContent 3 months ago
Remove deprecated code in the GitHub Workflows plugin. Code that still uses deprecated exports may break 7 months ago

UI

Replace react icons with Material UI icons in WorkflowTable 3 months ago
Replace icon imports with Material UI icons in WorkFlowActions 3 months ago
Replace icon imports with Material UI icons in WorkFlowStatus 3 months ago
Use shared icon components in WorkFlowStatus. Add shared icon components 3 months ago

Maintenance

Remove unused react icons dependency 3 months ago
Reorder dependencies in package.json files. Update yarn.lock 3 months ago
Correct export order. Keep module structure consistent 3 months ago

Set up Backstage in minutes with Roadie

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

Get a demo