blam
@@ -0,0 +1,6 @@
|
||||
---
|
||||
'@backstage/plugin-badges': patch
|
||||
'@backstage/plugin-badges-backend': patch
|
||||
---
|
||||
|
||||
These packages have been migrated to the [backstage/community-plugins](https://github.com/backstage/community-plugins) repository.
|
||||
@@ -1,186 +1,3 @@
|
||||
# Badges Backend
|
||||
# Deprecated
|
||||
|
||||
Backend plugin for serving badges to the `@backstage/plugin-badges` plugin.
|
||||
Default implementation uses
|
||||
[badge-maker](https://www.npmjs.com/package/badge-maker) for creating the
|
||||
badges, in SVG.
|
||||
|
||||
Currently, only entity badges are implemented. i.e. badges that may have entity
|
||||
specific information in them, and as such, are served from an entity specific
|
||||
endpoint.
|
||||
|
||||
## Installation
|
||||
|
||||
Install the `@backstage/plugin-badges-backend` package in your backend package:
|
||||
|
||||
```bash
|
||||
# From your Backstage root directory
|
||||
yarn --cwd packages/backend add @backstage/plugin-badges-backend
|
||||
```
|
||||
|
||||
Add the plugin using the following default setup for
|
||||
`src/plugins/badges.ts`:
|
||||
|
||||
```ts
|
||||
import {
|
||||
createRouter,
|
||||
createDefaultBadgeFactories,
|
||||
} from '@backstage/plugin-badges-backend';
|
||||
import { Router } from 'express';
|
||||
import { PluginEnvironment } from '../types';
|
||||
|
||||
export default async function createPlugin(
|
||||
env: PluginEnvironment,
|
||||
): Promise<Router> {
|
||||
return await createRouter({
|
||||
config: env.config,
|
||||
discovery: env.discovery,
|
||||
badgeFactories: createDefaultBadgeFactories(),
|
||||
tokenManager: env.tokenManager,
|
||||
logger: env.logger,
|
||||
identity: env.identity,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The `createDefaultBadgeFactories()` returns an object with badge factories to
|
||||
the badges-backend `createRouter()` to forward to the default badge builder. To
|
||||
customize the available badges, provide a custom set of badge factories. See
|
||||
further down for an example of a custom badge factories function.
|
||||
|
||||
Finally, you have to make the following changes in `src/index.ts`:
|
||||
|
||||
```ts
|
||||
// 1. import the plugin
|
||||
import badges from './plugins/badges';
|
||||
|
||||
...
|
||||
|
||||
const config = await loadBackendConfig({
|
||||
argv: process.argv,
|
||||
logger: rootLogger,
|
||||
});
|
||||
const createEnv = makeCreateEnv(config);
|
||||
|
||||
...
|
||||
// 2. Create a PluginEnvironment for the Badges plugin
|
||||
const badgesEnv = useHotMemoize(module, () => createEnv('badges'));
|
||||
|
||||
...
|
||||
|
||||
const apiRouter = Router();
|
||||
...
|
||||
// 3. Register the badges plugin in the router
|
||||
apiRouter.use('/badges', await badges(badgesEnv));
|
||||
...
|
||||
apiRouter.use(notFoundHandler());
|
||||
```
|
||||
|
||||
### New Backend System
|
||||
|
||||
The Badges backend plugin has support for the [new backend system](https://backstage.io/docs/backend-system/), here's how you can set that up:
|
||||
|
||||
In your `packages/backend/src/index.ts` make the following changes:
|
||||
|
||||
```diff
|
||||
import { createBackend } from '@backstage/backend-defaults';
|
||||
|
||||
const backend = createBackend();
|
||||
|
||||
// ... other feature additions
|
||||
|
||||
+ backend.add(import('@backstage/plugin-badges-backend'));
|
||||
|
||||
backend.start();
|
||||
```
|
||||
|
||||
## Badge builder
|
||||
|
||||
Badges are created by classes implementing the `BadgeBuilder` type. The default
|
||||
badge builder uses badge factories to turn a `BadgeContext` into a `Badge` spec
|
||||
for the `badge-maker` to create the SVG image.
|
||||
|
||||
### Default badges
|
||||
|
||||
A set of default badge factories are defined in
|
||||
[badges.ts](https://github.com/backstage/backstage/tree/master/plugins/badges-backend/src/badges.ts)
|
||||
as examples.
|
||||
|
||||
Additional badges may be provided in your application by defining custom badge
|
||||
factories, and provide them to the badge builder.
|
||||
|
||||
### Custom badges
|
||||
|
||||
To provide custom badges, create a badge factories function, and use that when
|
||||
creating the badges backend router.
|
||||
|
||||
```ts
|
||||
import type { Badge, BadgeContext, BadgeFactories } from '@backstage/plugin-badges-backend';
|
||||
export const createMyCustomBadgeFactories = (): BadgeFactories => ({
|
||||
<custom-badge-id>: {
|
||||
createBadge: (context: BadgeContext): Badge | null => {
|
||||
// ...
|
||||
return {
|
||||
label: 'my-badge',
|
||||
message: 'custom stuff',
|
||||
// ...
|
||||
};
|
||||
},
|
||||
},
|
||||
|
||||
// optional: include the default badges
|
||||
// ...createDefaultBadgeFactories(),
|
||||
});
|
||||
```
|
||||
|
||||
### Badge obfuscation
|
||||
|
||||
When you enable the obfuscation feature, the badges backend will obfuscate the entity names in the badge link. It's useful when you want your badges to be visible to the public, but you don't want to expose the entity names and also to protect your entity names from being enumerated.
|
||||
|
||||
To enable the obfuscation you need to activate the `obfuscation` feature in the `app-config.yaml`:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
badges:
|
||||
obfuscate: true
|
||||
```
|
||||
|
||||
:warning: **Warning**: The only endpoint to be publicly available is the `/entity/:entityUuid/:badgeId` endpoint. The other endpoints are meant for trusted internal users and should not be publicly exposed.
|
||||
|
||||
> Note that you cannot use env vars to set the `obfuscate` value. It must be a boolean value and env vars are always strings.
|
||||
|
||||
## API
|
||||
|
||||
The badges backend api exposes two main endpoints for entity badges. The
|
||||
`/badges` prefix is arbitrary, and the default for the example backend.
|
||||
|
||||
### If obfuscation is disabled (default or apps.badges.obfuscate: false)
|
||||
|
||||
- `/badges/entity/:namespace/:kind/:name/badge-specs` List all defined badges
|
||||
for a particular entity, in json format. See
|
||||
[BadgeSpec](https://github.com/backstage/backstage/tree/master/plugins/badges/src/api/types.ts)
|
||||
from the frontend plugin for a type declaration.
|
||||
|
||||
- `/badges/entity/:namespace/:kind/:name/badge/:badgeId` Get the entity badge as
|
||||
an SVG image. If the `accept` request header prefers `application/json` the
|
||||
badge spec as JSON will be returned instead of the image.
|
||||
|
||||
### If obfuscation is enabled (apps.badges.obfuscate: true)
|
||||
|
||||
- `/badges/entity/:namespace/:kind/:name/obfuscated` Get the obfuscated `entity url`.
|
||||
|
||||
> Note that endpoint have a embedded authMiddleware to authenticate the user requesting this endpoint. _It meant to be called from the frontend plugin._
|
||||
|
||||
- `/badges/entity/:entityUuid/:badgeId` Get the entity badge as an SVG image. If
|
||||
the `accept` request header prefers `application/json` the badge spec as JSON
|
||||
will be returned instead of the image.
|
||||
|
||||
- `/badge/entity/:entityUuid/badge-specs` List all defined badges for a
|
||||
particular entity, in json format. See
|
||||
[BadgeSpec](https://github.com/backstage/backstage/tree/master/plugins/badges/src/api/types.ts)
|
||||
from the frontend plugin for a type declaration.
|
||||
|
||||
## Links
|
||||
|
||||
- [Frontend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/badges)
|
||||
- [The Backstage homepage](https://backstage.io)
|
||||
This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-badges-backend` instead.
|
||||
|
||||
@@ -3,7 +3,8 @@
|
||||
"version": "0.4.0",
|
||||
"description": "A Backstage backend plugin that generates README badges for your entities",
|
||||
"backstage": {
|
||||
"role": "backend-plugin"
|
||||
"role": "backend-plugin",
|
||||
"moved": "@backstage-community/plugin-badges-backend"
|
||||
},
|
||||
"publishConfig": {
|
||||
"access": "public",
|
||||
@@ -60,5 +61,6 @@
|
||||
"@backstage/backend-test-utils": "workspace:^",
|
||||
"@backstage/catalog-client": "workspace:^",
|
||||
"@backstage/cli": "workspace:^"
|
||||
}
|
||||
},
|
||||
"deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-badges-backend instead."
|
||||
}
|
||||
|
||||
+2
-203
@@ -1,204 +1,3 @@
|
||||
# @backstage/plugin-badges
|
||||
# Deprecated
|
||||
|
||||
The badges plugin offers a set of badges that can be used outside of
|
||||
your backstage deployment, showing information related to data from
|
||||
the catalog, such as entity owner and lifecycle data for instance.
|
||||
|
||||
The available badges are setup in the `badges-backend` plugin, see
|
||||
link below for more details.
|
||||
|
||||
## Entity badges
|
||||
|
||||
To get markdown code for the entity badges, access the `Badges` context menu
|
||||
(three dots in the upper right corner) of an entity page like this:
|
||||
|
||||
|
||||
|
||||
This will popup a badges dialog showing all available badges for that entity like this:
|
||||
|
||||
|
||||
|
||||
## Badge obfuscation
|
||||
|
||||
The badges plugin supports obfuscating the badge URL to prevent it from being enumerated if the badges are used in a public context (like in Github repositories).
|
||||
|
||||
To enable obfuscation, set the `obfuscate` option to `true` in the `app.badges` section of your `app-config.yaml`:
|
||||
|
||||
```yaml
|
||||
app:
|
||||
badges:
|
||||
obfuscate: true
|
||||
```
|
||||
|
||||
Please note that if you have already set badges in your repositories and you activate the obfuscation you will need to update the badges in your repositories to use the new obfuscated URLs.
|
||||
|
||||
Please note that the backend part needs to be configured to support obfuscation. See the [backend plugin documentation](../badges-backend/README.md) for more details.
|
||||
|
||||
Also, you need to allow your frontend to access the configuration see <https://backstage.io/docs/conf/defining/#visibility> :
|
||||
|
||||
Example implementation would be in : `packages/app/src/config.d.ts`
|
||||
|
||||
```typescript
|
||||
export interface Config {
|
||||
app: {
|
||||
... some code
|
||||
badges: {
|
||||
/**
|
||||
* badges obfuscate
|
||||
* @visibility frontend
|
||||
*/
|
||||
obfuscate?: string;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
then include in the `packages/app/package.json` :
|
||||
|
||||
```json
|
||||
"files": [
|
||||
"dist",
|
||||
"config.d.ts"
|
||||
],
|
||||
"configSchema": "config.d.ts",
|
||||
```
|
||||
|
||||
## Sample Badges
|
||||
|
||||
Here are some samples of badges for the `artists-lookup` service in the Demo Backstage site:
|
||||
|
||||
- Component: [](https://demo.backstage.io/catalog/default/component/artist-lookup)
|
||||
- Lifecycle: [](https://demo.backstage.io/catalog/default/component/artist-lookup)
|
||||
- Owner: [](https://demo.backstage.io/catalog/default/component/artist-lookup)
|
||||
- Docs: [](https://demo.backstage.io/catalog/default/component/artist-lookup/docs)
|
||||
|
||||
## Usage
|
||||
|
||||
### Install the package
|
||||
|
||||
Install the `@backstage/plugin-badges` package in your frontend app package:
|
||||
|
||||
```bash
|
||||
# From your Backstage root directory
|
||||
yarn --cwd packages/app add @backstage/plugin-badges
|
||||
```
|
||||
|
||||
### Register plugin
|
||||
|
||||
This plugin requires explicit registration, so you will need to add it to your App's `plugins.ts` file:
|
||||
|
||||
```ts
|
||||
import { badgesPlugin } from '@backstage/plugin-badges';
|
||||
```
|
||||
|
||||
If you don't have a `plugins.ts` file see: [troubleshooting](#troubleshooting)
|
||||
|
||||
### Update your EntityPage
|
||||
|
||||
In your `EntityPage.tsx` file located in `packages\app\src\components\catalog` we'll need to make a few changes to get the Badges context menu added to the UI.
|
||||
|
||||
First we need to add the following imports:
|
||||
|
||||
```ts
|
||||
import { EntityBadgesDialog } from '@backstage/plugin-badges';
|
||||
import BadgeIcon from '@material-ui/icons/CallToAction';
|
||||
```
|
||||
|
||||
Next we'll update the React import that looks like this:
|
||||
|
||||
```ts
|
||||
import React from 'react';
|
||||
```
|
||||
|
||||
To look like this:
|
||||
|
||||
```ts
|
||||
import React, { ReactNode, useMemo, useState } from 'react';
|
||||
```
|
||||
|
||||
Then we have to add this chunk of code after all the imports but before any of the other code:
|
||||
|
||||
```ts
|
||||
const EntityLayoutWrapper = (props: { children?: ReactNode }) => {
|
||||
const [badgesDialogOpen, setBadgesDialogOpen] = useState(false);
|
||||
|
||||
const extraMenuItems = useMemo(() => {
|
||||
return [
|
||||
{
|
||||
title: 'Badges',
|
||||
Icon: BadgeIcon,
|
||||
onClick: () => setBadgesDialogOpen(true),
|
||||
},
|
||||
];
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<>
|
||||
<EntityLayout UNSTABLE_extraContextMenuItems={extraMenuItems}>
|
||||
{props.children}
|
||||
</EntityLayout>
|
||||
<EntityBadgesDialog
|
||||
open={badgesDialogOpen}
|
||||
onClose={() => setBadgesDialogOpen(false)}
|
||||
/>
|
||||
</>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
The last step is to wrap all the entity pages in the `EntityLayoutWrapper` like this:
|
||||
|
||||
```diff
|
||||
const defaultEntityPage = (
|
||||
+ <EntityLayoutWrapper>
|
||||
<EntityLayout.Route path="/" title="Overview">
|
||||
{overviewContent}
|
||||
</EntityLayout.Route>
|
||||
|
||||
<EntityLayout.Route path="/docs" title="Docs">
|
||||
<EntityTechdocsContent />
|
||||
</EntityLayout.Route>
|
||||
|
||||
<EntityLayout.Route path="/todos" title="TODOs">
|
||||
<EntityTodoContent />
|
||||
</EntityLayout.Route>
|
||||
+ </EntityLayoutWrapper>
|
||||
);
|
||||
```
|
||||
|
||||
Note: the above only shows an example for the `defaultEntityPage` for a full example of this you can look at [this EntityPage](https://github.com/backstage/backstage/blob/1fd9e6f601cabe42af8eb20b5d200ad1988ba309/packages/app/src/components/catalog/EntityPage.tsx#L318)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you don't have a `plugins.ts` file, you can create it with the path `packages/app/src/plugins.ts` and then import it into your `App.tsx`:
|
||||
|
||||
```diff
|
||||
+ import * as plugins from './plugins';
|
||||
|
||||
const app = createApp({
|
||||
apis,
|
||||
+ plugins: Object.values(plugins),
|
||||
bindRoutes({ bind }) {
|
||||
/* ... */
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Or simply edit `App.tsx` with:
|
||||
|
||||
```diff
|
||||
+ import { badgesPlugin } from '@backstage/plugin-badges'
|
||||
|
||||
const app = createApp({
|
||||
apis,
|
||||
+ plugins: [badgesPlugin],
|
||||
bindRoutes({ bind }) {
|
||||
/* ... */
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
- [Backend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/badges-backend)
|
||||
- [The Backstage homepage](https://backstage.io)
|
||||
This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-badges` instead.
|
||||
|
||||
@@ -3,7 +3,8 @@
|
||||
"version": "0.2.58",
|
||||
"description": "A Backstage plugin that generates README badges for your entities",
|
||||
"backstage": {
|
||||
"role": "frontend-plugin"
|
||||
"role": "frontend-plugin",
|
||||
"moved": "@backstage-community/plugin-badges"
|
||||
},
|
||||
"publishConfig": {
|
||||
"access": "public",
|
||||
@@ -52,5 +53,6 @@
|
||||
"react": "^16.13.1 || ^17.0.0 || ^18.0.0",
|
||||
"react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
|
||||
"react-router-dom": "6.0.0-beta.0 || ^6.3.0"
|
||||
}
|
||||
},
|
||||
"deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-badges instead."
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user