@im-open/im-github-deployments
v1.0.12
Published
A plugin to show GitHub deployments in Spotify Backstage Catalog
Downloads
48
Readme
IM GitHub Deployments Dashboard for Backstage
What is the IM GitHub Deployments Dashboard
The IM GitHub Deployments Dashboard plugin works in conjunction with the im-open/create-github-deployment GitHub workflow action to create and track GitHub deployments and deployment statuses.
Getting started
Update catalog-info.yaml
1. github.com/project-slug
- REQUIRED
The catalog-info.yaml
file will need to be updated so that the metadata.annotations
section contains a value for github.com/project-slug
. The project slug is the GitHub owner and repository name separated by a forward slash, i.e., im-open/im-github-deployments
.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: im-github-deployemnts
...
annotations:
github.com/project-slug: im-open/im-github-deployments
2. deployment-environments
- OPTIONAL, but recommended
Adding the metadata.deployment-environments
list allows the dashboard to be pre-populated with the expected deployment environments, and order their appearance in the dashboard. Otherwise, the deployment environments will be assumed to be:
- Dev
- QA
- Stage
- UAT
- Prod
- Demo
- Any other environments after this are ordered alphabetically
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: im-github-deployemnts
...
deployment-environments:
- Dev
- QA
- Stage
- Prod
annotations:
github.com/project-slug: im-open/im-github-deployments
Backstage Installation:
1. Add npm package
cd packages/app
yarn add @im-open/im-github-deployments
2. Add to backstage catalog
In catalog EntityPage.tsx
the reference to @im-open/im-github-deployments
needs to be added and the plugin control needs to be added.
.
├── ...
├── packages
│ └── app
│ ├── ...
│ ├── src
│ │ └── components
│ │ └── catalog
│ │ ├── ...
│ │ └── EntityPage.tsx
│ ├── ...
│ └──
└── ...
// imports
import { IMGitHubDeploymentsDashboard } from '@im-open/im-github-deployments';
...
const deploymentContent = (
<Grid container spacing={3} alignItems="stretch">
<Grid item xs={12} md={12} lg={12}>
<IMGitHubDeploymentsDashboard />
</Grid>
</Grid>
};
...
const defaultEntityPage = (
<EntityLayout>
<EntityLayout.Route path="/" title="Overview">
{overviewContent}
</EntityLayout.Route>
<EntityLayout.Route path="/deployments" title="Deployments">
{deploymentContent}
</EntityLayout.Route>
<EntityLayout.Route path="/ci-cd" title="CI/CD">
{cicdContent}
</EntityLayout.Route>
...
</EntityLayout>
);
...
The example adds the import
statement and adds the IMGitHubDeploymentDashboard
to the defaultEntityPage
, but the display of the deployment tab can be based on whatever your catalog considers a deployable entity that is tied to a GitHub workflow.
3. Authentication
The im-github-deployments
plugin relies on GitHub authentication. The user must have a GitHub login and access to the repository identified in the entity's project-slug
annotation.
Creating deployments via GitHub Workflows and Actions
Update deployment workflow to use the im-open/create-github-deployment action
After the deployment job, an update-the-deployment-board
job can report back the results of the deployment.
name: Project Deployment
on:
workflow_dispatch:
inputs:
tag:
description: The tag to deploy
type: string
required: true
environment:
description: The environment the branch, tag or SHA was deployed to
required: true
type: choice
options:
- Dev
- QA
- Stage
- Prod
instance:
description: The instance to deploy to
required: true
type: choice
options:
- Primary-slot1
- Primary-slot2
- Secondary-slot1
- Secondary-slot2
permissions:
# needed to create github deployments entries
deployments: write
jobs:
deploy-the-project:
outputs:
deployment_conclusion: ${{ steps.deployment.output.conclusion }}
...
update-the-deployment-board:
needs: [deploy-the-project]
steps:
- name: Create GitHub Deployment
id: create-deployment
uses: im-open/create-github-deployment@v1
with:
workflow-actor: ${{ github.actor }}
token: ${{ secrets.GITHUB_TOKEN }}
environment: ${{ input.environment }}
release-ref: ${{ input.tag }}
deployment-status: ${{ deploy-the-project.outputs.deployment_conclusion }}
entity: im-github-deployments
instance: ${{ input.instance }}
...