Merge pull request #18244 from adamdmharvey/adamdmharvey/pagerduty-config-schema

feat(pagerduty): Add config schema to PagerDuty Plugin
2023-06-15 13:23:18 +02:00
parent 3a6419fe6d 06d72a8d04
commit db6be74ae2
4 changed files with 68 additions and 33 deletions
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-pagerduty': minor
+---
+
+Adds a config schema definition so the plugin will validate with the new Backstage CLI "--strict" flag
@@ -3,26 +3,42 @@
 - Display relevant PagerDuty information about an entity within Backstage, such as the escalation policy, if there are any active incidents, and recent changes
 - Trigger an incident to the currently on-call responder(s) for a service

-# How it Works
+## How it Works

 - 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.
 - 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).
  - _Note: This feature is only available when providing the `pagerduty.com/integration-key` annotation_
 - Change events will be displayed in a separate tab. If the change event payload has additional links the first link only will be rendered.

-# Requirements
+## Requirements

 - 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 an Admin or Account Owner within your organization to request configuration of this plugin.

-# Support
+## Feature Overview
+
+### View any open incidents
+
+![PagerDuty plugin showing no incidents and the on-call rotation](doc/pd1.png)
+
+### Email link, and view contact information for staff on call
+
+![PagerDuty plugin showing on-call rotation contact information](doc/pd2.png)
+
+### Trigger an incident for a service
+
+![PagerDuty plugin popup modal for creating an incident](doc/pd3.png)
+
+![PagerDuty plugin showing an active incident](doc/pd4.png)
+
+## Support

 If you need help with this plugin, please reach out on the [Backstage Discord server](https://discord.gg/backstage-687207715902193673).

-# Integration Walk-through
+## Integration Walk-through

-## In PagerDuty
+### In PagerDuty

-### Integrating With a PagerDuty Service
+#### Integrating With a PagerDuty Service

 1. From the **Configuration** menu, select **Services**.
 2. There are two ways to add an integration to a service:
@@ -33,9 +49,9 @@ If you need help with this plugin, please reach out on the [Backstage Discord se
 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.
   ![](https://pdpartner.s3.amazonaws.com/ig-template-copy-integration-key.png)

-## In Backstage
+### In Backstage

-### Install the plugin
+#### Install the plugin

 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`.

@@ -86,7 +102,7 @@ const overviewContent = (
 );
 ```

-### Configure the plugin
+#### Configure the plugin

 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:

@@ -95,7 +111,7 @@ annotations:
  pagerduty.com/integration-key: [INTEGRATION_KEY]
 ```

-### The homepage component
+#### The homepage component

 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.

@@ -140,9 +156,9 @@ $ PAGERDUTY_TOKEN='<TOKEN>' yarn start

 This will proxy the request by adding an `Authorization` header with the provided token.

-### Optional configuration
+#### Optional configuration

-#### Annotating with Service ID
+##### Annotating with Service ID

 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

@@ -160,12 +176,12 @@ Your browser URL should now be located at `https://pagerduty.com/service-directo

 _Note: When annotating with `pagerduty.com/service-id`, the feature to Create Incidents is not currently supported_

-#### Custom Events URL
+##### Custom Events URL

 If you want to override the default URL used for events, you can add it to `app-config.yaml`:

 ```yaml
-pagerduty:
+pagerDuty:
  eventsBaseUrl: 'https://events.pagerduty.com/v2'
 ```

@@ -187,7 +203,7 @@ proxy:
    allowedMethods: ['GET']
 ```

-# How to Uninstall
+## How to Uninstall

 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.
 2. Remove the added code snippets from `EntityPage.tsx`
@@ -199,19 +215,3 @@ yarn remove --cwd packages/app @backstage/plugin-pagerduty
 ```

 4. [Delete the integration](https://support.pagerduty.com/docs/services-and-integrations#delete-an-integration-from-a-service) from the service in PagerDuty
-
-# Feature Overview
-
-## View any open incidents
-
-![PagerDuty plugin showing no incidents and the on-call rotation](doc/pd1.png)
-
-## Email link, and view contact information for staff on call
-
-![PagerDuty plugin showing on-call rotation contact information](doc/pd2.png)
-
-## Trigger an incident for a service
-
-![PagerDuty plugin popup modal for creating an incident](doc/pd3.png)
-
-![PagerDuty plugin showing an active incident](doc/pd4.png)
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface Config {
+  /**
+   * Configuration for the PagerDuty plugin
+   * @visibility frontend
+   */
+  pagerDuty?: {
+    /**
+     * Optional Events Base URL to override the default.
+     * @visibility frontend
+     */
+    eventsBaseUrl?: string;
+  };
+}
@@ -67,6 +67,8 @@
    "msw": "^1.0.0"
  },
  "files": [
-    "dist"
-  ]
+    "dist",
+    "config.d.ts"
+  ],
+  "configSchema": "config.d.ts"
 }