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
yarn workspace app add @veecode-platform/backstage-plugin-github-workflows
If your repo uses an older yarn layout
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
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
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
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
# .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
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
metadata:
annotations:
github.com/workflows: filePath.yml,filePath2.yml
Optional advanced form to customize card label and tooltip
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
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
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
<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 7 months 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
- 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.