Github Workflows Plugin

The GithubWorkflows plugin provides an alternative for manually triggering GitHub workflows from within your Backstage component.

The plugin offers two distinct approaches to integrate with your component:

• On-demand workflows, which are configured via annotations in your project's catalog-info.yaml.
• A complete listing of the workflows available in your project.

Our community

💬 Join Us

Join our community to resolve questions about our Plugins. We look forward to welcoming you!

  Go to Community  🚀

Getting Started:

Before installing the plugin, there are some prerequisites to ensure its functionality:

• Have a locally installed Backstage project, :heavy_check_mark: How to create a Backstage app :page_with_curl: .
• Set up the catalog and integrate with GitHub with a Personal Access Token or Github App , :heavy_check_mark: How to configure the integration :page_with_curl: .
• Configure GitHub authentication, :heavy_check_mark: How to configure authentication :page_with_curl: .
• Configure the default GitHub Actions plugin, :heavy_check_mark: Documentation of the Github actions plugin :page_with_curl: .

Installation

If you are using yarn 3.x:

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

If you are using other versions:

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

Configuration

We'll divide the configuration into three steps:

1- Proxy Configuration.

1.1 - Using github auth provider:

:information_source: Make sure you have an github auth provider in your devportal. See how Add Github Auth Provider 📃

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

proxy:
  '/github/api':
    target: https://api.github.com/repos
    allowedHeaders: ['Authorization', 'X-GitHub-Api-Version']
    headers: 
      Accept: application/vnd.github+json
      X-GitHub-Api-Version: "2022-11-28"

2- To trigger workflows directly from our component, it's important to add the workflow_dispatch: step in our GitHub workflow, like this:

# Workflow Example

name: Deploy Next.js site to Pages

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

 ....

Even if no parameters are passed to this key, it must be present in the file to enable event triggering through the Backstage component.

Parameters

:information_source: It's possible to set parameters in the workflow as well, and the plugin understands them. Actions will only be triggered if the required parameters are sent.

3- We need a primary annotation, commonly used by all Backstage components,github.com/project-slug, where the project name is set.

As a main prerequisite, this annotation must be declared in the catalog-info.yamlof the component that will receive this functionality.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: "Example Component"
  description: "An example Backstage Components"
  links:
    - title: Website
      url: http://backstage.io
    - title: Documentation
      url: https://backstage.io/docs
    - title: Storybook
      url: https://backstage.io/storybook
    - title: Discord Chat
      url: https://discord.com/invite/EBHEGzX
  annotations:
+    github.com/project-slug: owner/repo
    backstage.io/techdocs-ref: dir:.
   
spec:
  type: website
  lifecycle: experimental
  owner: default

Workflows List

The component essentially lists all the workflows available in the repository. In its header, we highlight the select that filters all available branches in the project and the refresh button to update the workflow states.

The table is divided by workflow name, status, action, and link to the repository.

In some cases, to trigger an action, it may require parameters, as configured in your workflow. Instead of an action button, a modal is displayed to set the requested parameters:

When an event is triggered in the workflow, the status is updated, and the conclusion is returned after refreshing the table.

We encourage users to create a new tab in their catalog named "Workflows" and keep the "CI-CD" tab with the default Backstage component. In the following sections, we'll explain the integration between the two plugins.

Example of adding the new tab to a serviceEntityPage packages/app/src/components/catalog/EntityPage.tsx

+ import { GithubWorkflowsList, isGithubAvailable } from '@veecode-platform/backstage-plugin-github-workflows'
...

+ const cicdContent = (
+  <EntitySwitch>
+    <EntitySwitch.Case if={isGithubActionsAvailable}>
+      <GithubWorkflowsList/>
+    </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 to enable CI/CD for it. You can read more
+        about annotations in Backstage by clicking the button below."
+        action={
+          <Button
+            variant="contained"
+            color="primary"
+            href="https://backstage.io/docs/features/software-catalog/well-known-annotations"
+          >
+            Read more
+          </Button>
+        }
+      />
+    </EntitySwitch.Case>
+  </EntitySwitch>
+ );

...

Workflow Cards

For this component, we need to add a special annotation, github.com/workflows, like this:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: "Example Component"
  description: "An example Backstage Components"
  links:
    - title: Website
      url: http://backstage.io
    - title: Documentation
      url: https://backstage.io/docs
    - title: Storybook
      url: https://backstage.io/storybook
    - title: Discord Chat
      url: https://discord.com/invite/EBHEGzX
  annotations:
    github.com/project-slug: owner/repo
    backstage.io/techdocs-ref: dir:.
+   github.com/workflows: fileName.yaml
   
spec:
  type: website
  lifecycle: experimental
  owner: default

The composition of the annotation works like this:

:information_source: It's important to note that you can add multiple workflow paths, separated by commas, like this:

github.com/workflows: filePath.yml,filePath2.yml,filePath3.yml,

The functionality is identical to the workflow listing component, with the main difference being that only the workflows passed via annotation are listed, instead of all the workflows in the repository.

As an indication, we use the cards directly in the component overview, like this:

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

+ import { isGithubWorkflowsAvailable, GithubWorkflowsCard } from '@veecode-platform/backstage-plugin-github-workflows'

....

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {entityWarningContent}
    <Grid item md={6}>
      <EntityAboutCard variant="gridItem" />
    </Grid>
    <Grid item md={6} xs={12}>
      <EntityCatalogGraphCard variant="gridItem" height={400} />
    </Grid>

+    <EntitySwitch>
+      <EntitySwitch.Case if={isGithubWorkflowsAvailable}>
+        <Grid item lg={8} xs={12}>
+            <GithubWorkflowsCard />
+        </Grid>
+      </EntitySwitch.Case>
+    </EntitySwitch>
    
    <Grid item md={4} xs={12}>
      <EntityLinksCard />
    </Grid>
    <Grid item md={8} xs={12}>
      <EntityHasSubcomponentsCard variant="gridItem" />
    </Grid> 
  </Grid>
);

It works like this:

In its header we have the select of the repository branches and a refresh button.

In its body, the workflows that were added via annotation, and each card has its status, workflow name as label and the action button.

As with the Workflow list, there are cases of workflows that trigger parameters before releasing their actions, and the card has the same behavior as the Workflow list, it triggers a modal so that the inputs are set:

The functioning of the actions is also similar, when you click on the action button, it updates the status according to the github response:

Workflow Details & Logs

In the Workflows List component, clicking on the Logs column:

In the Card component, clicking under the component label:

The Details component is then rendered with information about the last time the workflow was run, it stores information about the author of the commit, the commit id with link to github, the status and duration of the workflow in total.

In addition, in the body of the page, it contains the name and filePath of the workflow and how it was executed, followed by the jobs:

In each Job we have the steps executed and at the end we have the log of that job, which can be rendered in the component itself or expanded to a new modal:

ℹ️ For github profile avatars to render, add this url to be allowed in your app-config.yaml

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