Incoming webhooks
Incoming webhooks can be configured on a Sourcegraph instance in order to receive webhook events from code hosts. This allows Sourcegraph to react more quickly to events that occur outside the instance instead of polling for changes.
Webhooks are currently implemented to speed up two types of external events:
- Keeping batch changes changeset details up to date
- Keeping code on Sourcegraph fresh by responding to new code being pushed to a repository
See the table below for code host compatibility:
Code host | Batch changes | Code push | User permissions |
---|---|---|---|
GitHub | 🟢 | 🟢 | 🟢 |
GitLab | 🟢 | 🟢 | 🔴 |
Bitbucket Server / Datacenter | 🟢 | 🟢 | 🔴 |
Bitbucket Cloud | 🟢 | 🟢 | 🔴 |
To receive webhooks both Sourcegraph and the code host need to be configured. To configure Sourcegraph, add an incoming webhook. Then configure webhooks on your code host
Adding an incoming webhook
Before adding an incoming webhook you should ensure that you have at least one code host connection configured.
The incoming webhook will be configured to accept events from a specific code host connection based on its type and URN.
- Navigate to Site Admin > Incoming webhooks
- Click Add webhook
- Fill out the form:
- Webhook name: Descriptive name for the webhook.
- Code host type: Select from the dropdown. This will be filtered based on code host connections added on your instance.
- Code host URN: The URN for the code host. Again, this will be filtered by code host connections added on your instance.
- Secret: An arbitrary shared secret between Sourcegraph and the code host. A default value is provided, but you are free to change it.
- Click Create
The incoming webhook will now be created, and you will be redirected to a page showing more details.
Use the unique URL present on the details page to configure the webhook on your code host.
Configuring webhooks on the code host
The instructions for setting up webhooks on the code host are specific to each code host type.
GitHub
Batch changes
- Copy the webhook URL displayed after adding the incoming webhook as mentioned above
- On GitHub, go to the settings page of your organization. From there, click Settings, then Webhooks, then Add webhook.
- Fill in the webhook form:
- Payload URL: the URL you copied above from Sourcegraph.
- Content type: this must be set to
application/json
. - Secret: the secret token you configured Sourcegraph to use above.
- Which events: select Let me select individual events, and then enable:
- Issue comments
- Pull requests
- Pull request reviews
- Pull request review comments
- Check runs
- Check suites
- Statuses
- Active: ensure this is enabled.
- Click Add webhook.
- Confirm that the new webhook is listed.
Done! Sourcegraph will now receive webhook events from GitHub and use them to sync pull request events, used by batch changes, faster and more efficiently.
Code push
Follow the same steps as above, but ensure you include the push
event under Let me select individual events
User permissions
Follow the same steps as above, but ensure you include the following events under Let me select individual events:
Collaborator add, remove, or changed
Memberships
Organizations
Repositories
Teams
When one of these events occur, a permissions sync will trigger for the relevant user or repository.
GitLab
Batch changes
- Copy the webhook URL displayed after adding the incoming webhook as mentioned above
- On GitLab, go to your project, and then Settings > Webhooks (or Settings > Integration on older GitLab versions that don't have the Webhooks option).
- Fill in the webhook form:
- URL: the URL you copied above from Sourcegraph.
- Secret token: the secret token you configured Sourcegraph to use above.
- Trigger: select Merge request events and Pipeline events.
- Enable SSL verification: ensure this is enabled if you have configured SSL with a valid certificate in your Sourcegraph instance.
- Click Add webhook.
- Confirm that the new webhook is listed below Project Hooks.
Done! Sourcegraph will now receive webhook events from GitLab and use them to sync merge request events, used by batch changes, faster and more efficiently.
NOTE: We currently do not support system webhooks as these provide a different set of payloads.
Code push
Follow the same steps as above, but ensure you include the Push events
trigger.
Bitbucket server
Batch changes
The Sourcegraph Bitbucket Server plugin enables the Bitbucket Server / Bitbucket Data Center instance to send webhooks to Sourcegraph.
- Install the Sourcegraph Bitbucket Server plugin on your Bitbucket Server / Bitbucket Data Center instance.
- On your Bitbucket Server / Bitbucket Data Center instance, go to Administration > Add-ons > Sourcegraph
- Fill in the Add a webhook form
- Name: A unique name representing your Sourcegraph instance.
- Scope:
global
. - Endpoint: The URL found after creating an incoming webhook.
- Events:
repo:build_status
,pr:activity:status
,pr:activity:event
,pr:activity:rescope
,pr:activity:merge
,pr:activity:comment
,pr:activity:reviewers
,pr:participant:status
- Secret: The secret you configured when creating the incoming webhook.
- Confirm that the new webhook is listed under All webhooks with a timestamp in the Last successful column.
Done! Sourcegraph will now receive webhook events from Bitbucket Server / Bitbucket Data Center and use them to sync pull request events, used by batch changes, faster and more efficiently.
Code push
Follow the same steps as above, but ensure you tick the Push
option. If asked for a specific event, use repo:refs_changed
.
Bitbucket cloud
Batch changes
- On Bitbucket Cloud, go to each repository, and then Repository settings > Webhooks.
- Click Add webhook.
- Fill in the webhook form:
- Title: Any title.
- URL: The URL found after creating an incoming webhook.
- Triggers: Select Build status created and Build status updated under Repository, and every item under Pull request.
- Click Save.
- Confirm that the new webhook is listed below Repository hooks.
Done! Sourcegraph will now receive webhook events from Bitbucket Cloud and use them to sync pull request events, used by batch changes, faster and more efficiently.
Code push
Follow the same steps as above, but ensure you tick the Push
option.
Webhook logging
Sourcegraph can track incoming webhooks from code hosts to more easily debug issues with webhook delivery. These webhooks can be viewed in two places depending on how they were added:
- Via Site Admin > [Repositories] > Incoming webhooks
- Deprecated Via code host connection: Site Admin > [Batch Changes] > Incoming webhooks
By default, sites without database encryption enabled will retain three days of webhook logs. Sites with encryption will not retain webhook logs by default, as webhooks may include sensitive information; these sites can enable webhook logging and optionally configure encryption for them by using the settings below.
Enabling webhook logging
Webhook logging is controlled by the webhook.logging
site configuration
option. This option is an object with the following keys:
Key | Type | Default | Description |
---|---|---|---|
enabled |
boolean |
If true , incoming webhooks will be stored. |
true if no site encryption is enabled; false otherwise. |
retention |
string |
The length of time to retain the webhooks, expressed as a valid Go duration. | 72h |
Examples
To disable webhook logging:
{ "webhook.logging": {"enabled": false} }
To retain webhook logs for one day:
{ "webhook.logging": { "enabled": false, "retention": "24h" } }
Encrypting webhook logs
Webhook logs can be encrypted by specifying a webhookLogKey
in the on-disk database encryption site configuration.
Deprecation notice
As of Sourcegraph 4.3.0 webhooks added via code host configuration are deprecated and support will be removed in release 4.6.0.
This includes any webhooks pointed at URLs starting with the following:
.api/github-webhooks
.api/gitlab-webhooks
.api/bitbucket-server-webhooks
.api/bitbucket-cloud-webhooks
In order to continue using webhooks you need to follow the steps below to add an incoming webhook and then update the webhook configured on your code host with the new webhook url which will look something like https://sourcegraph-instance/.api/webhooks/{UUID}