Add Bitbucket Server Event Integration

Signed-off-by: David Lilienfeld <davidlilienfeld4@gmail.com>
2023-08-27 18:36:03 -04:00
parent 753c1a1c78
commit 7b3ed9b928
29 changed files with 1715 additions and 45 deletions
@@ -26,7 +26,47 @@ dependency to `@backstage/plugin-catalog-backend-module-bitbucket-server` to you
 yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-bitbucket-server
 ```

-And update your backend by adding the following line:
+### Installation with New Backend System
+
+```ts
+// optional if you want HTTP endpojnts to receive external events
+// backend.add(import('@backstage/plugin-events-backend/alpha'));
+// optional if you want to use AWS SQS instead of HTTP endpoints to receive external events
+// backend.add(import('@backstage/plugin-events-backend-module-aws-sqs/alpha'));
+backend.add(
+  import('@backstage/plugin-events-backend-module-bitbucket-server/alpha'),
+);
+backend.add(
+  import('@backstage/plugin-catalog-backend-module-bitbucket-server/alpha'),
+);
+```
+
+You need to decide how you want to receive events from external sources like
+
+- [via HTTP endpoint](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
+- [via an AWS SQS queue](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-aws-sqs/README.md)
+
+Further documentation:
+
+- <https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md>
+- <https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-aws-sqs/README.md>
+- <https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-bitbucket-server/README.md>
+
+### Installation with Legacy Backend System
+
+#### Installation without Events Support
+
+You will have to add the entity provider in the catalog initialization code of your
+backend. The provider is not installed by default, therefore you have to add a
+dependency to `@backstage/plugin-catalog-backend-module-bitbucket-server` to your backend
+package.
+
+```bash
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-bitbucket-server
+```
+
+And then add the entity provider to your catalog builder:

 ```ts title="packages/backend/src/index.ts"
 backend.add(import('@backstage/plugin-catalog-backend'));
@@ -37,6 +77,60 @@ backend.add(
 /* highlight-add-end */
 ```

+#### Installation with Events Support
+
+Please follow the installation instructions at
+
+- <https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md>
+- <https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-bitbucket-server/README.md>
+
+Additionally, you need to decide how you want to receive events from external sources like
+
+- [via HTTP endpoint](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
+  - Bitbucket Server events webhook url should be set to `{backstageBaseUrl}/api/events/http/bitbucketServer`
+- [via an AWS SQS queue](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-aws-sqs/README.md)
+
+Set up your provider
+
+```ts title="packages/backend/src/plugins/catalog.ts"
+import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
+/* highlight-add-start */
+import { BitbucketServerEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-server';
+/* highlight-add-end */
+
+import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend';
+import { Router } from 'express';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  const builder = await CatalogBuilder.create(env);
+  builder.addProcessor(new ScaffolderEntitiesProcessor());
+  /* highlight-add-start */
+  const bitbucketServerProvider = BitbucketServerEntityProvider.fromConfig(
+    env.config,
+    {
+      catalogApi: new CatalogClient({ discoveryApi: env.discovery }),
+      logger: env.logger,
+      scheduler: env.scheduler,
+      events: env.events,
+      tokenManager: env.tokenManager,
+    },
+  );
+  env.eventBroker.subscribe(bitbucketServerProvider);
+  builder.addEntityProvider(bitbucketServerProvider);
+  /* highlight-add-end */
+  const { processingEngine, router } = await builder.build();
+  await processingEngine.start();
+  return router;
+}
+```
+
+**Attention:**
+`catalogApi` and `tokenManager` are required at this variant
+compared to the one without events support.
+
 ## Configuration

 To use the entity provider, you'll need a [Bitbucket Server integration set up](locations.md).