Set the GitHub webhook

With the GitHub webhook, Astrolabe hears about a push, a tag, a release or a workflow as soon as it happens. The Events tab of each component fills in, and the people concerned are told when a workflow fails.

You do it once, as an administrator: a secret in Astrolabe, then the same secret in GitHub.

Before you start

• GitHub is set up in Administration › Company connections. Without it, the Webhooks screen has no GitHub card.
• The GitHub and Events plugins are on in Administration › Plugins.
• Choose a secret: a long random text. You enter the same one in GitHub.

🔧 Save the secret in Astrolabe

1. In the left sidebar, at the bottom, click Administration.

2. Under PLATFORM, click Webhooks.

3. On the GitHub card, click Configure.

4. In the window Configure GitHub Secret, next to Webhook URL, click Copy address. Keep that address: you paste it in GitHub below. It ends with /api/orion-events/github, for example https://astrolabe.acme.example/api/orion-events/github.

5. In Webhook Secret, type your secret, for example a-long-random-text.

6. Click Save Secret.

The card now says No call received since Astrolabe started. and offers Manage.

A sign-in proxy in front of Astrolabe?

GitHub never signs in: let its address through, or the calls never reach Astrolabe. See Open Astrolabe to your tools.

🔧 Add the webhook in GitHub

Set it on the organization to cover all its repositories at once, or on a single repository. This part happens in GitHub and was not checked on a live instance.

1. In GitHub, open your organization (or the repository), then Settings › Webhooks.

2. Click Add webhook.

3. Fill in the form:

   Field	What to enter
   Payload URL	The address you copied in Astrolabe
   Content type	application/json
   Secret	The same secret as in Astrolabe
   SSL verification	Enable SSL verification

4. Under Which events would you like to trigger this webhook?, choose Let me select individual events., then tick:

   Event	What Astrolabe does with it
   Pushes	One line per commit in the Events tab
   Branch or tag creation	One line per tag
   Releases	One line per published release
   Workflow runs	Start and end of each workflow, and a notification when it fails
   Workflow jobs	The failed step of a workflow
   Pull requests	A notification to the owners of the component
   Pull request reviews	A notification to the owners of the component

5. Keep Active ticked and click Add webhook.

GitHub sends a first test call right away.

🔗 Link a repository to its component

Astrolabe puts an event on the component whose catalog-info.yaml names the repository:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  annotations:
    github.com/project-slug: acme/order-service
spec:
  type: service
  lifecycle: production
  owner: team-checkout

The value is <organization>/<repository>, exactly as in the address of the repository on GitHub.

✅ Check that it works

1. Push a commit to a linked repository.

2. In Administration › Webhooks, the GitHub card says Last call accepted followed by a date.

3. In the Catalog, open the component, then its Events tab. The commit is there, for example Dev Acme pushed the commit d448215 on main — “Fix the checkout total”.

✅ That's it!

Common problems

What you see	What to do
On the GitHub card, Refused (1), last at …: the source signs with another secret than Astrolabe's: set the same one on both sides.	Click Manage, Replace, type the secret that GitHub uses and click Save Secret. Or put Astrolabe's secret in the GitHub webhook.
On the GitHub card, Refused (1), last at …: the source sent no secret: set the same secret in its webhook settings.	The GitHub webhook has no Secret. Edit it in GitHub and type the same secret as in Astrolabe.
The card still says No call received since Astrolabe started., and in GitHub, under Recent Deliveries, the response of a call is a sign-in page instead of Received	A sign-in proxy answers in place of Astrolabe. Let the address through: Open Astrolabe to your tools.
The card still says No call received since Astrolabe started., and in GitHub the call answers 400 with unsupported media type application/x-www-form-urlencoded	Content type is application/x-www-form-urlencoded. Edit the webhook in GitHub and choose application/json.
On the GitHub card, 2 events reached nobody: the plugin of this source is turned off, so its events are dropped. Switch it on in Administration › Plugins.	In Administration › Plugins, switch GitHub on.
The card says Last call accepted, but the Events tab of the component stays empty	The repository is not linked to the component. Check github.com/project-slug in its catalog-info.yaml: <organization>/<repository>, as on GitHub.
The Events tab shows the pushes but no workflow	Workflow runs is not ticked in the GitHub webhook. Edit it and tick it.
No GitHub card on the Webhooks screen	GitHub is not set up in Administration › Company connections. Set it up first.

Still stuck?

Write to support@forgeit.fr with what the GitHub card says.

Next: Check that your tools reach Astrolabe.