Backstage Highlights Plugin is configurable and customizable plugin for viewing the most important information about your entity.
We have a lot information from different plugins and also in Overview tab, but sometimes:
The "Highlights" shall provide you possibility to create such small, useful view.
If you haven't already, check out the Backstage docs and create a Backstage application with
npx @backstage/create-app
Then, you will need to install and configure the highlights plugins for the frontend and the backend.
Install:
cd packages/app
yarn add @rsc-labs/backstage-highlights-plugin
Add the card to packages/app/src/components/catalog/EntityPage.tsx
:
// import:
import { EntityHighlightsCard } from '@rsc-labs/backstage-highlights-plugin';
// use it in entity view
const overviewContent = (
<Grid container
...
<Grid item md={12} xs={12}>
<<EntityHighlightsCard />
</Grid>
</Grid>
)
For the best UX we strongly recommend to use as much horizontal space as possible. Thanks to that you will have your highlights on top of your page as a bar.
Of course, you can also make it smaller and near the other card.
At this moment, "highlights plugin" comes with built-in support of basic information about Git. As you can see in above picture, we support following fields:
You can click at the field and get more information. For example, when you click on latest tag you will get longer history:
Other fields can have similar functionality, but it depends on the provider (Github API provides more information)
At this moment built-in fields supports Github and Gitlab (see: Configuration of Backend).
By default, you can use EntityHighlights without any parameter - it gives you above built-in fields. However, you may want change a behaviour or implement your custom fields. Below you can find an interface:
/** @public */
export interface EntityHighlightsProps {
fields? : EHighlightFields[],
customFields?: HighlightCustomField[]
}
1) fields - this parameter describes what built-in you would like to see and in what order 2) customFields - this parameter can let you define your own field. Every custom field contains:
Install:
cd packages/backend
yarn add @rsc-labs/backstage-highlights-plugin-backend
Create a file packages/backend/src/plugins/highlights.ts
:
import {
createRouter,
} from '@rsc-labs/backstage-highlights-plugin-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
discovery: env.discovery,
tokenManager: env.tokenManager,
logger: env.logger,
config: env.config
});
}
Add the plugin to packages/backend/src/index.ts
:
// import:
import highlights from './plugins/highlights';
...
async function main() {
...
// add env
const highlightsEnv = useHotMemoize(module, () => createEnv('highlights'));
...
// add to router
apiRouter.use('/highlights', await highlights(highlightsEnv));
...
}
Backend plugin supports two providers - Github and Gitlab. They are providing information for built-in fields mentioned in Frontend plugin. Plugin uses following annotations from catalog-info.yaml:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: example-website
annotations:
github.com/project-slug: rsc-labs/backstage-changelog-plugin
gitlab.com/project-slug: owner/project
gitlab.com/instance: gitlab.instance.com
Both /project-slug are supported (so your component can be in github or gitlab). In theory case if you have both annotations, github takes precedence.
gitlab.com/instance annotation is used for Multiple Gitlab instances
To have properly working Github or Gitlab, you need also provide information about token and potentially about base url. You have two options how to provide it 1) Custom highlights configuration 2) Integration configuration
Below you can find implemented both options:
highlights:
gitlab:
token: ${GITLAB_TOKEN}
apiBaseUrl: https://gitlab.com/api/v4
github:
token: ${GITHUB_TOKEN}
integrations:
gitlab:
- token: ${GITLAB_TOKEN}
github:
- token: ${GITHUB_TOKEN}
If provided, "highlights" configuration takes precendece over "integrations". Note: "highlights" configuration requires providing "apiBaseUrl", while it is not needed in "integrations" (if you are using default one)
We start supporting also multiple Gitlab instances for both highlights and integrations in app-config. Below you can find instruction and example of configuration.
1) If you would like to use "highlights" configuration, then you need to change it to a list instead of one object. Additionally, we need to be able to figure out which instance is used for which entity, so host annotation is needed (see example below). For backward compatibility, we still support single object. 2) Similarly with integrations. We already support a list, but to use multiple Gitlab instances, you need to also provide host and apiBaseUrl (see example below)
Example of both options in one configuration:
highlights:
gitlab:
- host: gitlab.com
token: ${GITLAB_TOKEN}
apiBaseUrl: https://gitlab.com/api/v4
- host: gitlab1.com
token: ${GITLAB2_TOKEN}
apiBaseUrl: https://gitlab1.com/api/v4
github:
token: ${GITHUB_TOKEN}
integrations:
gitlab:
- host: gitlab.com
token: ${GITLAB_TOKEN}
- host: gitlab1.com
token: ${GITLAB2_TOKEN}
apiBaseUrl: https://gitlab1.com/api/v4
github:
- host: github.com
token: ${GITHUB_TOKEN}
At the same time, your entity shall have proper annotations, for example:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: example-website
annotations:
github.com/project-slug: rsc-labs/backstage-changelog-plugin
gitlab.com/project-slug: owner/project
gitlab.com/instance: gitlab1.com
Taking above example - component example-website will use gitlab1.com, which maps to values:
Please remember that "highlights" configuration (if present) takes precendence over "integrations".
[ ] Unit tests
[ ] More fields to support
Contributions are welcome and they are greatly appreciated!
Licensed under the Mozilla Public License, Version 2.0: https://www.mozilla.org/en-US/MPL/2.0/
© 2023 RSC https://rsoftcon.com/