paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Added more details as to how to setup events for GitHub discovery

Browse Source 
Signed-off-by: Andre Wanlin <awanlin@spotify.com>

Update docs/integrations/github/discovery.md

Co-authored-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com>

Update docs/integrations/github/discovery.md

Co-authored-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com>

Improvements based on feedback

Signed-off-by: Andre Wanlin <awanlin@spotify.com>

Reworded

Signed-off-by: Andre Wanlin <awanlin@spotify.com>
This commit is contained in:
Andre Wanlin
2025-05-23 15:05:45 -05:00
parent e656551f8f
commit 2bc1a40cad
1 changed files with 136 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integrations/github/discovery.md
+136 -19
View File
@@ -37,32 +37,149 @@ backend.add(import('@backstage/plugin-catalog-backend-module-github'));
## Events Support
The catalog module for GitHub comes with events support enabled.
This will make it subscribe to its relevant topics (`github.push`,
`github.repository`) and expects these events to be published
via the `EventsService`.
The catalog module for GitHub comes with events support enabled. This will make it subscribe to its relevant topics (`github.push`, `github.repository`) and expects these events to be published via the `EventsService`.
Additionally, you should install the
[event router by `events-backend-module-github`](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-github/README.md)
which will route received events from the generic topic `github` to more specific ones
based on the event type (e.g., `github.push`).
### Prerequisites
In order to receive Webhook events by GitHub, you have to decide how you want them
to be ingested into Backstage and published to its `EventsService`.
You can decide between the following options (extensible):
There are two Prerequisites to use the builtin events support:
- [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)
1. Creating a webhook in GitHub
2. Installing and configuring `@backstage/plugin-events-backend-module-github`
#### Configure Webhooks in GitHub
You can check the official docs to [configure your webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks) and to [secure your request](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks).
The webhook(s) will need to be configured to react to `push` and
`repository` events.
The webhook(s) will need to be configured to react to `push` and `repository` events.
Certain actions like `transferred` by the `repository` event type
will not be supported when you use repository webhooks.
Please check the GitHubs documentation for these event types and
its actions.
Certain actions like `transferred` by the `repository` event type will not be supported when you use repository webhooks. Please check the GitHub documentation for these event types and their actions.
When creating the webhook in GitHub the "Payload URL" will looks something along these lines: `https://<your-intance-name>/api/events/http/github` and the "Content Type" should be `application/json`.
The GitHub Webhooks UI will send a trial event to validate it can connect when you save your new Webhook. It is possible to retry this trial event if it fails and you want to send it again. Additionally there is a Recent Deliveries tab you can use to validate that the events are being fired should you need to do any later troubleshooting.
#### Install and Configure GitHub Events Module
In order to use the built-in events support you'll need to install and configure `@backstage/plugin-events-backend-module-github`. This module will route received events from the generic topic `github` to more specific ones based on the event type (e.g., `github.push`). These more specific events are what the builtin events support is expecting.
First we need to add the package:
```bash title="from your Backstage root directory"
yarn --cwd packages/backend add @backstage/plugin-events-backend-module-github
```
Then we need to add it to your backend:
```ts title="in packages/backend/src/index.ts"
backend.add(import('@backstage/plugin-events-backend'));
/* highlight-add-start */
backend.add(import('@backstage/plugin-events-backend-module-github'));
/* highlight-add-end */
```
Finally you will want to configure it:
```yaml title="app-config.yaml
events:
modules:
github:
webhookSecret: ${GITHUB_WEBHOOK_SECRET}
```
Though this last step is technically optional, you'll want to include it to be sure the events being received are from GitHub and not from an external bad actor.
The value of `${GITHUB_WEBHOOK_SECRET}` in this example would be the same that you used when creating the webhook on GitHub.
### Events Setup using HTTP endpoint
Using the HTTP endpoint for events just requires adding some additional configuration to your `app-config.yaml` as it is a built in feature of the Events backend, here's what that would look like:
```yaml title="app-config.yaml
events:
http:
topics:
- github
```
This will then expose an endpoint like this: <http://localhost/api/events/http/github>
### Events Setup using AWS SQS module
Alternatively to using the HTTP endpoint you can use the AWS SQS module, here's how.
First we need to add the package:
```bash title="from your Backstage root directory"
yarn --cwd packages/backend add @backstage/plugins-events-backend-module-aws-sqs
```
Then we need to add it to your backend:
```ts title="in packages/backend/src/index.ts"
backend.add(import('@backstage/plugin-events-backend'));
backend.add(import('@backstage/plugin-events-backend-module-github'));
/* highlight-add-start */
backend.add(import('@backstage/plugins-events-backend-module-aws-sqs'));
/* highlight-add-end */
```
Finally you will want to configure it:
```yaml title="app-config.yaml
events:
modules:
awsSqs:
awsSqsConsumingEventPublisher:
topics:
github:
queue:
url: 'https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue'
region: us-east-2
```
The [AWS SQS module `README`](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-aws-sqs/README.md#configuration) has more details on the configuration options, the example above includes on the required options.
### Events Setup using Google Pub/Sub module
Alternatively to using the HTTP endpoint you can use the Google Pub/Sub module, here's how.
First we need to add the package:
```bash title="from your Backstage root directory"
yarn --cwd packages/backend add @backstage/plugin-events-backend-module-google-pubsub
```
Then we need to add it to your backend:
```ts title="in packages/backend/src/index.ts"
backend.add(import('@backstage/plugin-events-backend'));
backend.add(import('@backstage/plugin-events-backend-module-github'));
/* highlight-add-start */
backend.add(import('@backstage/plugin-events-backend-module-google-pubsub'));
/* highlight-add-end */
```
Finally you will want to configure it:
```yaml title="app-config.yaml
events:
modules:
googlePubSub:
googlePubSubConsumingEventPublisher:
subscriptions:
# A unique key for your subscription, to be used in logging and metrics
mySubscription:
# The fully qualified name of the subscription
subscriptionName: 'projects/my-google-project/subscriptions/github-enterprise-events'
# The event system topic to transfer to. This can also be just a plain string
targetTopic:
# This example picks the topic name from a message attribute + a prefix
fromMessageAttribute:
attributeName: 'x-github-event'
withPrefix: 'github.'
```
The [Google Pub/Sub module `README`](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-google-pubsub/README.md#configuration) has more details on the configuration options, the example above includes on the required options.
## Configuration