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.
  

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, :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

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

Configuration

We'll divide the configuration into three steps:

1- Proxy Configuration.

In the app-config.yaml file:

1proxy:
2  '/github-workflows':
3    target: https://api.github.com/repos
4    allowedHeaders: ['Authorization', 'X-GitHub-Api-Version']
5    headers: 
6      Authorization: Bearer ${GITHUB_TOKEN_SECRET}
7      Accept: application/vnd.github+json
8      X-GitHub-Api-Version: "2022-11-28"

:information_source: Remember to set the ${GITHUB_TOKEN_SECRET} variable with your GitHub personal token.

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

1# Workflow Example
2
3name: Deploy Next.js site to Pages
4
5on:
6  push:
7    branches: ["master"]
8+ workflow_dispatch:
9
10 ....

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.

1apiVersion: backstage.io/v1alpha1
2kind: Component
3metadata:
4  name: "Example Component"
5  description: "An example Backstage Components"
6  links:
7    - title: Website
8      url: http://backstage.io
9    - title: Documentation
10      url: https://backstage.io/docs
11    - title: Storybook
12      url: https://backstage.io/storybook
13    - title: Discord Chat
14      url: https://discord.com/invite/EBHEGzX
15  annotations:
16+    github.com/project-slug: example/ExampleComponent
17    backstage.io/techdocs-ref: dir:.
18   
19spec:
20  type: website
21  lifecycle: experimental
22  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

1+ import { GithubWorkflowsList } from '@veecode-platform/backstage-plugin-github-workflows'
2
3const serviceEntityPage = (
4  <EntityLayout>
5    <EntityLayout.Route path="/" title="Overview">
6      {overviewContent}
7    </EntityLayout.Route>
8
9    <EntityLayout.Route path="/ci-cd" title="CI/CD">
10      {cicdContent}
11    </EntityLayout.Route>
12    
13+   <EntityLayout.Route path="/workflows" title="Workflows">
14+       <EntitySwitch>
15+    	<EntitySwitch.Case if={isGithubActionsAvailable}>
16+      		<GithubWorkflowsList/>
17+    	</EntitySwitch.Case>
18+    	<EntitySwitch.Case>
19+      	<EmptyState
20+        title="No CI/CD available for this entity"
21+        missing="info"
22+        description="You need to add an annotation to your component if you want to enable CI/CD for it. You can read more about 
23+        annotations in Backstage by clicking the button below."
24+        action={
25+          <Button
26+            variant="contained"
27+            color="primary"
28+            href="https://backstage.io/docs/features/software-catalog/well-known-annotations"
29+          >
30+            Read more
31+          </Button>
32+        }
33+      />
34+    		</EntitySwitch.Case>
35+  		</EntitySwitch>
36+    </EntityLayout.Route>
37
38    <EntityLayout.Route path="/api" title="API">
39      <Grid container spacing={3} alignItems="stretch">
40        <Grid item md={6}>
41          <EntityProvidedApisCard />
42        </Grid>
43        <Grid item md={6}>
44          <EntityConsumedApisCard />
45        </Grid>
46      </Grid>
47    </EntityLayout.Route>
48
49    <EntityLayout.Route path="/dependencies" title="Dependencies">
50      <Grid container spacing={3} alignItems="stretch">
51        <Grid item md={6}>
52          <EntityDependsOnComponentsCard variant="gridItem" />
53        </Grid>
54        <Grid item md={6}>
55          <EntityDependsOnResourcesCard variant="gridItem" />
56        </Grid>
57      </Grid>
58    </EntityLayout.Route>
59
60    <EntityLayout.Route path="/docs" title="Docs">
61      {techdocsContent}
62    </EntityLayout.Route>
63  </EntityLayout>
64);
65

---

Workflow Cards

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

1apiVersion: backstage.io/v1alpha1
2kind: Component
3metadata:
4  name: "Example Component"
5  description: "An example Backstage Components"
6  links:
7    - title: Website
8      url: http://backstage.io
9    - title: Documentation
10      url: https://backstage.io/docs
11    - title: Storybook
12      url: https://backstage.io/storybook
13    - title: Discord Chat
14      url: https://discord.com/invite/EBHEGzX
15  annotations:
16    github.com/project-slug: example/ExampleComponent
17    backstage.io/techdocs-ref: dir:.
18+   github.com/workflows: fileName.yaml
19   
20spec:
21  type: website
22  lifecycle: experimental
23  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:

1github.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

1+ import { isGithubWorkflowsAvailable, GithubWorkflowsCard } from '@veecode-platform/backstage-plugin-github-workflows'
2
3....
4
5const overviewContent = (
6  <Grid container spacing={3} alignItems="stretch">
7    {entityWarningContent}
8    <Grid item md={6}>
9      <EntityAboutCard variant="gridItem" />
10    </Grid>
11    <Grid item md={6} xs={12}>
12      <EntityCatalogGraphCard variant="gridItem" height={400} />
13    </Grid>
14
15+    <EntitySwitch>
16+      <EntitySwitch.Case if={isGithubWorkflowsAvailable}>
17+        <Grid item lg={8} xs={12}>
18+            <GithubWorkflowsCard />
19+        </Grid>
20+      </EntitySwitch.Case>
21+    </EntitySwitch>
22    
23    <Grid item md={4} xs={12}>
24      <EntityLinksCard />
25    </Grid>
26    <Grid item md={8} xs={12}>
27      <EntityHasSubcomponentsCard variant="gridItem" />
28    </Grid> 
29  </Grid>
30);

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:

Integration with github actions plugin

For a greater experience, we highlight the use of the default github actions plugin that backstage already provides, where it lists all the runs executed in the repository, and in it are also present all the logs of each action.

In the Workflows List component, integration occurs by clicking on the Logs column:

In the Card component, the integration occurs by clicking under the component label:

With it correctly installed and available in the CI-CD tab, we were able to integrate the triggers of the actions with their logs and all their history: