@pagerduty/backstage-plugin 0.7.2-next.1 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +14 -231
  2. package/package.json +20 -15
package/README.md CHANGED
@@ -4,250 +4,33 @@
4
4
  [![npm version](https://badge.fury.io/js/@pagerduty%2Fbackstage-plugin.svg)](https://badge.fury.io/js/@pagerduty%2Fbackstage-plugin)
5
5
  [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
6
6
 
7
- **Note:** If you are migrating from *@backstage/plugin-pagerduty* you can follow these instructions [here](https://github.com/PagerDuty/backstage-plugin?tab=readme-ov-file#how-to-migrate-from-backstageplugin-pagerduty).
7
+ **Bring the power of PagerDuty to Backstage!**
8
+ The PagerDuty plugin reduces the cognitive load on developers responsible for maintaining services in production. Instead of having to go to PagerDuty's console, you can now access the necessary information directly within Backstage. This includes finding active incidents or opening a new incident, reviewing recent changes made to the service, and checking who is on-call.
8
9
 
9
- ## Integration Benefits
10
+ ## Features
10
11
 
11
- - Display relevant PagerDuty information about an entity within Backstage, such as the active incidents or recent changes.
12
- - Quickly check who is on call for a service.
13
- - Trigger an incident to the currently on-call responder(s) for a service.
12
+ - **[Trigger New Incident](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#trigger-an-incident-for-a-service>)** - Easily create new incidents for your service directly from Backstage. This feature saves time and reduces the need for context switching.
13
+ - **[See Active Incidents](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#view-any-open-incidents>)** - View all active incidents for a service directly in Backstage.
14
+ - **[Check for Recent Changes](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#view-change-events-associated-to-a-service>)** - Identify recent changes that may be the root cause of potential issues with your service.
15
+ - **[Identify On-Call Personnel](<https://pagerduty.github.io/backstage-plugin-docs/capabilities/#see-and-contact-on-call-staff>)** - Quickly determine who is responsible for a failing service and resolve the incident as quickly as possible. This feature allows companies to spend more time solving problems rather than determining who should solve them.
14
16
 
15
- ## How it Works
17
+ ## Getting Started
16
18
 
17
- - The Backstage PagerDuty plugin allows PagerDuty information about a Backstage entity to be displayed within Backstage. This includes active incidents, recent change events, as well as the current on-call responders' names, email addresses, and links to their profiles in PagerDuty.
18
- - Incidents can be manually triggered via the plugin with a user-provided description, which will in turn notify the current on-call responders. Alternatively, the plugin can be configured with an optional `readOnly` property to suppress the ability to trigger incidents from the plugin.
19
- - **Note:** This feature is only available when providing the *`pagerduty.com/integration-key`* annotation.
20
- - Change events will be displayed in a separate tab. If the change event payload has additional links, only the first link will be rendered.
19
+ Find the complete project's documentation [here](https://pagerduty.github.io/backstage-plugin-docs/).
21
20
 
22
- ## Requirements
21
+ ### Installation
23
22
 
24
- - Setup of the PagerDuty plugin for Backstage requires a PagerDuty Admin role in order to generate the necessary authorizations, such as the API token. If you do not have this role, please reach out to a **Global Admin** or **Account Owner** within your organization to request configuration of this plugin.
23
+ The installation of the PagerDuty plugin for Backstage is done with *yarn* as all other plugins in Backstage. This plugin follows a modular approach which means that every individual component will be a separate package (e.g. frontend, backend, common). In this case, you are installing a **frontend plugin**.
25
24
 
26
- ## Feature Overview
27
-
28
- ### View any open incidents
29
-
30
- ![PagerDuty plugin showing no incidents and the on-call rotation](doc/pd1.png)
31
-
32
- ### Email link, and view contact information for staff on call
33
-
34
- ![PagerDuty plugin showing on-call rotation contact information](doc/pd2.png)
35
-
36
- ### Trigger an incident for a service
37
-
38
- ![PagerDuty plugin popup modal for creating an incident](doc/pd3.png)
39
-
40
- ![PagerDuty plugin showing an active incident](doc/pd4.png)
41
-
42
- ## Integration Walk-through
43
-
44
- ### In PagerDuty
45
-
46
- #### Integrating With a PagerDuty Service
47
-
48
- 1. From the **Configuration** menu, select **Services**.
49
- 2. There are two ways to add an integration to a service:
50
- - **If you are adding your integration to an existing service**: Click the **name** of the service you want to add the integration to. Then, select the **Integrations** tab and click the **New Integration** button.
51
- - **If you are creating a new service for your integration**: Please read the documentation in section [Configuring Services and Integrations](https://support.pagerduty.com/docs/services-and-integrations#section-configuring-services-and-integrations) and follow the steps outlined in the [Create a Service](https://support.pagerduty.com/docs/services-and-integrations#create-a-service) section, selecting **Backstage** as the **Integration Type** in step 5. Continue with the [*"In Backstage"*](https://github.com/PagerDuty/backstage-plugin?tab=readme-ov-file#in-backstage) section (below) once you have finished these steps.
52
- 3. Enter an **Integration Name** in the format `monitoring-tool-service-name` (e.g. `Backstage-Shopping-Cart`) and select **Backstage** from the Integration Type menu.
53
- 4. Click the **Add Integration** button to save your new integration. You will be redirected to the Integrations tab for your service.
54
- 5. An **Integration Key** will be generated on this screen. Keep this key saved in a safe place, as it will be used when you configure the integration with **Backstage** in the next section.
55
- ![screenshot-for-integration-key-page](https://pdpartner.s3.amazonaws.com/ig-template-copy-integration-key.png)
56
-
57
- ### In Backstage
58
-
59
- #### Install the plugin
60
-
61
- The file paths mentioned in the following steps are relative to your app's root directory — for example, the directory created by following the [Getting Started](https://backstage.io/docs/getting-started/) guide and creating your app with `npx @backstage/create-app`.
62
-
63
- First, from your Backstage root directory, install the PagerDuty plugin via CLI:
25
+ To install this plugin run the following command from the Backstage root folder.
64
26
 
65
27
  ```bash
66
28
  yarn add --cwd packages/app @pagerduty/backstage-plugin
67
29
  ```
68
30
 
69
- Next, add the plugin to `EntityPage.tsx` in `packages/app/src/components/catalog` by adding the following code snippets.
70
-
71
- Add the following imports to the top of the file:
72
-
73
- ```ts
74
- import {
75
- isPluginApplicableToEntity as isPagerDutyAvailable,
76
- EntityPagerDutyCard,
77
- } from '@pagerduty/backstage-plugin';
78
- ```
79
-
80
- Find `const overviewContent` in `EntityPage.tsx`, and add the following snippet inside the outermost `Grid` defined there, just before the closing `</Grid>` tag:
81
-
82
- ```ts
83
- <EntitySwitch>
84
- <EntitySwitch.Case if={isPagerDutyAvailable}>
85
- <Grid item md={6}>
86
- <EntityPagerDutyCard />
87
- </Grid>
88
- </EntitySwitch.Case>
89
- </EntitySwitch>
90
- ```
91
-
92
- When you're done, the `overviewContent` definition should look something like this:
93
-
94
- ```ts
95
- const overviewContent = (
96
- <Grid ...>
97
- ...
98
- <EntitySwitch>
99
- <EntitySwitch.Case if={isPagerDutyAvailable}>
100
- <Grid item md={6}>
101
- <EntityPagerDutyCard />
102
- </Grid>
103
- </EntitySwitch.Case>
104
- </EntitySwitch>
105
- </Grid>
106
- );
107
- ```
108
-
109
- #### Configure the plugin
110
-
111
- First, [annotate](https://backstage.io/docs/features/software-catalog/descriptor-format#annotations-optional) the appropriate entity with the PagerDuty integration key in its `.yaml` configuration file:
112
-
113
- ```yaml
114
- annotations:
115
- pagerduty.com/integration-key: [INTEGRATION_KEY]
116
- ```
117
-
118
- #### The homepage component
119
-
120
- You may also add the component to the homepage of Backstage. Edit the `HomePage.tsx` file, import `PagerDutyHomepageCard` and add it to the home page. e.g.
121
-
122
- ```typescript jsx
123
- ...
124
- export const homePage = (
125
- <Page themeId="home">
126
- ...
127
- <Content>
128
- <CustomHomepageGrid config={defaultConfig}>
129
- ...
130
- <PagerDutyHomepageCard
131
- name="My Service"
132
- serviceId="<service id>"
133
- integrationKey="<integration key>"
134
- readOnly={false}
135
- />
136
- </CustomHomepageGrid>
137
- </Content>
138
- </Page>
139
- );
140
- ```
141
-
142
- Next, provide the [API token](https://support.pagerduty.com/docs/generating-api-keys#generating-a-general-access-rest-api-key) that the client will use to make requests to the [PagerDuty API](https://developer.pagerduty.com/docs/rest-api-v2/rest-api/).
143
-
144
- Add the proxy configuration in `app-config.yaml`:
145
-
146
- ```yaml
147
- proxy:
148
- ...
149
- '/pagerduty':
150
- target: https://api.pagerduty.com
151
- headers:
152
- Authorization: Token token=${PAGERDUTY_TOKEN}
153
- ```
154
-
155
- Then, start the backend, passing the PagerDuty API token as an environment variable:
156
-
157
- ```bash
158
- PAGERDUTY_TOKEN='<TOKEN>' yarn start
159
- ```
160
-
161
- This will proxy the request by adding an `Authorization` header with the provided token.
162
-
163
- #### Optional configuration
164
-
165
- ##### Annotating with Service ID
166
-
167
- If you want to integrate a PagerDuty service with Backstage but don't want to use an integration key, you can also [annotate](https://backstage.io/docs/features/software-catalog/descriptor-format#annotations-optional) the appropriate entity with a PagerDuty Service ID instead
168
-
169
- ```yaml
170
- annotations:
171
- pagerduty.com/service-id: [SERVICE_ID]
172
- ```
173
-
174
- This service ID can be found by navigating to a Service within PagerDuty and pulling the ID value out of the URL.
175
-
176
- 1. From the **Configuration** menu within PagerDuty, select **Services**.
177
- 2. Click the **name** of the service you want to represent for your Entity.
178
-
179
- Your browser URL should now be located at `https://pagerduty.com/service-directory/[SERVICE_ID]`.
180
-
181
- **Note:** *When annotating with `pagerduty.com/service-id`, the feature to Create Incidents is not currently supported*.
182
-
183
- ##### Custom Events URL
184
-
185
- If you want to override the default URL used for events, you can add it to `app-config.yaml`:
186
-
187
- ```yaml
188
- pagerDuty:
189
- eventsBaseUrl: 'https://events.pagerduty.com/v2'
190
- ```
191
-
192
- > **Note:** PagerDuty accounts based in Europe use a different url so you need to override it here if that is your case.
193
-
194
- To suppress the rendering of the actionable incident-creation button, the `PagerDutyCard` can also be instantiated in `readOnly` mode:
195
-
196
- ```ts
197
- <PagerDuty readOnly />
198
- ```
199
-
200
- **WARNING**: In current implementation, the PagerDuty plugin requires the `/pagerduty` proxy endpoint be exposed by the Backstage backend as an unprotected endpoint, in effect enabling PagerDuty API access using the configured `PAGERDUTY_TOKEN` for any user or process with access to the `/pagerduty` Backstage backend endpoint. If you regard this as problematic, consider using the plugin in `readOnly` mode (`<PagerDutyCard readOnly />`) using the following proxy configuration:
201
-
202
- ```yaml
203
- proxy:
204
- '/pagerduty':
205
- target: https://api.pagerduty.com
206
- headers:
207
- Authorization: Token token=${PAGERDUTY_TOKEN}
208
- # prohibit the `/pagerduty` proxy endpoint from servicing non-GET requests
209
- allowedMethods: ['GET']
210
- ```
211
-
212
- ## How to Uninstall
213
-
214
- 1. Remove any configuration added in Backstage yaml files, such as the proxy configuration in `app-config.yaml` and the integration key in an entity's annotations.
215
- 2. Remove the added code snippets from `EntityPage.tsx`
216
- 3. Remove the plugin package:
217
-
218
- ```bash
219
- # From your Backstage root directory
220
- yarn remove --cwd packages/app @pagerduty/backstage-plugin
221
- ```
222
-
223
- 4. [Delete the integration](https://support.pagerduty.com/docs/services-and-integrations#delete-an-integration-from-a-service) from the service in PagerDuty
224
-
225
- ## How to migrate from @backstage/plugin-pagerduty
226
-
227
- If you are migrating from the Pagerduty plugin that was maintained by Spotify, the steps to migrate are pretty simple.
228
-
229
- 1. Remove the Backstage package from your project
230
-
231
- ```bash
232
- # From your Backstage root directory
233
- yarn remove --cwd packages/app @backstage/plugin-pagerduty
234
- ```
235
-
236
- 2. Install the new PagerDuty plugin for Backstage
237
-
238
- ```bash
239
- # From your Backstage root directory
240
- yarn add --cwd packages/app @pagerduty/backstage-plugin
241
- ```
242
-
243
- 3. Replace all occurrences of **@backstage/plugin-pagerduty** with **@pagerduty/backstage-plugin** in your components
244
-
245
- 4. Re-install dependencies and run Backstage locally to test that everything is working
31
+ ### Configuration
246
32
 
247
- ```bash
248
- # From your Backstage root directory
249
- yarn install && yarn dev
250
- ```
33
+ To configure this frontend plugin follow the instructions on the `Getting Started` section of the project's documentation [here](https://pagerduty.github.io/backstage-plugin-docs/).
251
34
 
252
35
  ## Support
253
36
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@pagerduty/backstage-plugin",
3
3
  "description": "A Backstage plugin that integrates towards PagerDuty",
4
- "version": "0.7.2-next.1",
4
+ "version": "0.7.2",
5
5
  "main": "dist/index.esm.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "license": "Apache-2.0",
@@ -33,29 +33,30 @@
33
33
  "clean": "backstage-cli package clean"
34
34
  },
35
35
  "dependencies": {
36
- "@backstage/catalog-model": "^1.4.1",
37
- "@backstage/core-components": "^0.13.4",
38
- "@backstage/core-plugin-api": "^1.5.3",
39
- "@backstage/errors": "^1.2.1",
40
- "@backstage/plugin-catalog-react": "^1.8.3",
41
- "@backstage/plugin-home-react": "^0.1.2",
42
- "@backstage/theme": "^0.4.1",
36
+ "@backstage/catalog-model": "^1.4.3",
37
+ "@backstage/core-components": "^0.13.8",
38
+ "@backstage/core-plugin-api": "^1.8.0",
39
+ "@backstage/errors": "^1.2.3",
40
+ "@backstage/plugin-catalog-react": "^1.9.1",
41
+ "@backstage/plugin-home-react": "^0.1.5",
42
+ "@backstage/theme": "^0.4.4",
43
43
  "@material-ui/core": "^4.12.2",
44
44
  "@material-ui/icons": "^4.9.1",
45
45
  "@material-ui/lab": "4.0.0-alpha.61",
46
- "@types/react": "^16.13.1 || ^17.0.0 || ^18.0.0",
47
46
  "classnames": "^2.2.6",
48
47
  "luxon": "^3.4.1",
48
+ "react-use": "^17.2.4"
49
+ },
50
+ "peerDependencies": {
49
51
  "react": "^16.13.1 || ^17.0.0 || ^18.0.0",
50
52
  "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
51
- "react-router-dom": "6.0.0-beta.0 || ^6.3.0",
52
- "react-use": "^17.2.4"
53
+ "react-router-dom": "6.0.0-beta.0 || ^6.3.0"
53
54
  },
54
55
  "devDependencies": {
55
- "@backstage/cli": "^0.22.12",
56
- "@backstage/core-app-api": "^1.9.1",
57
- "@backstage/dev-utils": "^1.0.20",
58
- "@backstage/test-utils": "^1.4.2",
56
+ "@backstage/cli": "^0.24.0",
57
+ "@backstage/core-app-api": "^1.11.1",
58
+ "@backstage/dev-utils": "^1.0.24",
59
+ "@backstage/test-utils": "^1.4.5",
59
60
  "@commitlint/cli": "^17.7.1",
60
61
  "@commitlint/config-conventional": "^17.7.0",
61
62
  "@testing-library/dom": "^8.0.0",
@@ -64,8 +65,12 @@
64
65
  "@testing-library/user-event": "^14.0.0",
65
66
  "@types/luxon": "^3.3.1",
66
67
  "@types/node": "^16.11.26",
68
+ "@types/react": "^16.13.1 || ^17.0.0 || ^18.0.0",
67
69
  "copyfiles": "^2.4.1",
68
70
  "msw": "^1.2.4",
71
+ "react": "^16.13.1 || ^17.0.0 || ^18.0.0",
72
+ "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
73
+ "react-router-dom": "6.0.0-beta.0 || ^6.3.0",
69
74
  "typescript": "^4.8.4"
70
75
  },
71
76
  "files": [