GitHub Webhook configuration
A GitHub Webhook enables DevOps Intelligence to receive notifications dynamically (as relevant events occur). When specified events occur, GitHub sends an HTTP POST payload to the webhook's configured URL. DevOps Intelligence supports this capability as a necessary complement to GitHub.
Use the procedures in the following sections to create the GitHub Webhook necessary to receive these notifications.
Setup instructions for your organization/repository
Prerequisite requirements
- Administrator access to the GitHub repository.
- A server or service endpoint that can receive webhook payloads.
- HTTPS endpoint for secure webhook delivery.
- You must create a secret token.
Use the following procedure to create a secret token:
- Navigate to Tools Configuration.
- Switch to Bring your own tools.
- In the Create New Token tab, select token type as Webhooks.
- Press the Create button to generate the token.
After confirming the prerequiste requirements, decide whether you want to set up events for all repositories in your organization or choose individual repositories. Create a webhook at the organization level to cover all repositories, or at the repository level for specific repos.
Organization Level setup
Use the following procedure to set up a GitHub Webhook for your organization (compare at Repository Level setup immediately following this procedure):
- Navigate to your repository on GitHub (or organization in the event you prefer to set up an Organization level hook).
- Click on Settings --> Webhooks
- Click Add webhook
- Configure the following settings:
- Payload URL: The URL of your endpoint (must be HTTPS for production). The Url would the tenant host along with "/dash/api/broker/v1/webhook/collector"
- Content type: application/json
- Secret: Set a secure secret to validate webhook payloads
- Events: Choose which events should trigger the webhook. Choose from the following:
- Code scanning alerts
- Dependabot alerts
- Deployment statuses
- Issue comments
- Issues
- Meta
- Member
- Organizations (only for Org hooks)
- Pull request review comments
- Pull request reviews
- Pull requests
- Pushes
- Workflow jobs
- Workflow runs
- Active: Check this box to enable the webhook.
- Click Add webhook to save.
Repository Level setup
A repository level Webhook is required whether you have an organizational level Webhook. If you have set up an organization Webhook, you must still perform the setup procedure for specific repositories that will be in use.
The procedure is the same for organization level setup with two exceptions in the Events options:
- There is no Organization option.
- Repository setup contains an additional option, Collaborator add remove changed.
To begin repository level setup navigate to the repository for which you set a Webhook, and follow the procedure described for organizational setup.
Setup Github workflow for retrying failed events
All events processed by your endpoint are displayed on the GitHub webhook page. If your tenant is temporarily unavailable, those events will not be processed. GitHub tracks each event and its status. DevOps Intelligence GitHub integration includes support for retrying failed events.
You can implement this feature at the organizational level or the repository level. Implementing it at the organizational level enables retries at the repository level for repositories associated with that organization.
To implement event retrying at the organizational level, create a workflow file using the latest workflow repository file as a guide. The workflow file path takes the following form:
https://github.kyndryl.net/MCMP-DevOps-Intelligence/devops-reusable-workflow
The following variables are necessary:
- ORGANIZATION_NAME: The name of your GitHub organization.
- REPO_NAME: The name of your GitHub Repository (If you are creating workflow for any repository)
- HOOK_ID: The unique identifier for the webhook you want to retry. You would get this ID in the url when you edit the created hook.
- HOSTNAME: The base URL for your GitHub Enterprise or API endpoint.
- WEBHOOK_TOKEN: A secret token stored in your repository or organization secrets, used for authentication.
Token of type Webhooks can be used only once in a tenant. If you have already generated use the existing token.
Troubleshooting
If you encounter data synchronizing problems, use the following checklist to troubleshoot the fail point:
- Check webhook delivery logs in GitHub
- Ensure your endpoint is accessible from the internet
- Check your server logs for errors processing the payload
- Do not disable or skip any of the required events in the GitHub webhook configuration. Disabling any required events can lead to data mismatch. If a mismatch occurs due to incomplete events, the entire technical service must be deleted and re-onboarded.