GitHub
UTMStack v12 collects GitHub events through webhooks. GitHub posts each event over HTTPS to the UTMStack Forwarder (the Collector in the web interface), which checks the event's signature and forwards it to UTMStack. Nothing is installed on GitHub.
Connection details
| Setting | Value |
|---|---|
| Card on the Integrations page | Github (category DevOps) |
| Data type | github |
| Listener on the Collector | HTTPS on port 7020, path /github, listening on all addresses |
| Authentication | HMAC signature (a hash of each request made with a shared secret) in the X-Hub-Signature-256 header |
| Format UTMStack expects | GitHub's JSON webhook payloads (content type application/json) |
| Parsing pipeline | github/github.yaml. The Filters button in the drawer opens it. |
| Detection rules | 13 rules for the github data type. The Rules button in the drawer lists them. |
Before you begin
A Collector must be installed and online. If you do not have one, see UTMStack Forwarder.
GitHub sends from the internet, so port 7020/TCP on the Collector host must be reachable from GitHub. GitHub publishes the addresses its webhooks come from in the
hookslist ofhttps://api.github.com/meta; you can allow only those.The Collector host needs a DNS name and a TLS certificate for that name issued by a public certificate authority.
You need the
integrations.writepermission to enable the integration from the web interface, and admin access to the GitHub repository or owner access to the organization.
GitHub only delivers webhooks to HTTPS endpoints with a certificate issued by a public certificate authority. Self-signed certificates are rejected. Make sure the Collector host has a valid certificate for its domain before you register the webhook.
Step 1: Load the certificate on the Collector
Load the certificate and its private key once per Collector. Use a certificate file that contains the full chain: your certificate followed by the intermediate certificates (for example fullchain.pem from Let's Encrypt). The Collector presents exactly what is in that file, and GitHub needs the intermediates to trust it.
Web interface: in the Github card, under Enable this integration remotely, select the Collector. In the TLS certificate box, choose the Certificate, the Private key and, if needed, the CA certificate, then click Upload certificate. The box then says "A valid certificate is already loaded on this Collector."
Command line on the Collector host:
sudo /opt/utmstack-forwarder/utmstack_forwarder load-tls-certs /path/to/fullchain.pem /path/to/privkey.pem
The Collector reads the certificate for each new connection. When you renew it, load the new files the same way; you do not need to restart anything. The same certificate is used by every TLS and HTTPS listener on that Collector.
Step 2: Enable the integration
- 1
- 2
Check the settings
Under Enable this integration remotely, select the Collector. The other fields are already set for GitHub: Protocol HTTPS, Port 7020, Authentication HMAC signature, Path
/githuband Signature headerX-Hub-Signature-256. Unlike syslog integrations, the HTTPS listener uses the port you type here. - 3
Enable it and copy the secret
Click Enable integration. UTMStack shows a secret token once: "Store this token securely — it won't be shown again." Copy it now. You need it in GitHub.
To do the same on the Collector host instead, run:
sudo /opt/utmstack-forwarder/utmstack_forwarder enable-integration github 7020 httpsThe terminal prints the secret token once. The Forwarder keeps it in /opt/utmstack-forwarder/certs/integration-http-github.token.
A new token is created only when that file does not exist. If you enable the integration while the file is already there, no token is shown and the existing one stays valid; read it with sudo cat /opt/utmstack-forwarder/certs/integration-http-github.token. Disabling the integration deletes the file, so enabling it again creates a new token that you must also enter in GitHub.
Step 3: Register the webhook in GitHub
In your repository or organization, go to Settings → Webhooks → Add webhook and fill in the form:
| GitHub field | Value |
|---|---|
| Payload URL | https://<collector-domain>:7020/github |
| Content type | application/json |
| Secret | The token from step 2 |
| SSL verification | Keep it enabled |
| Which events | Send me everything, or select the event types you want |
Save the webhook. GitHub sends a ping event right away.
The setup guide in UTMStack fills in your UTMStack server's address in the Payload URL. Keep it only if the Collector runs on the UTMStack server; otherwise use the domain name of the Collector host. The name must match the certificate you loaded in step 1.
Step 4: Check that events arrive
In GitHub, open the webhook and its Recent Deliveries tab. The
pingdelivery should show the response code 204, which means the Collector accepted it.In the Github drawer, click View logs. Log Explorer opens on the
logsdata set with thegithubdata type for the last 24 hours. You can also open Log Explorer and choose the data type yourself.Expand an event. The Parsed fields view should show the webhook fields under
log., and theerrorsfield should be empty.Within about 20 minutes, a source named
githubappears on Configure > Data Sources under Direct. All webhook events on this Collector are stored under that one source name.
You can also check from Log Explorer in SQL mode:
SELECT `@timestamp`, dataSource, errors, raw
FROM logs
WHERE dataType = 'github'
AND `@timestamp` > now() - INTERVAL 1 DAY
ORDER BY `@timestamp` DESC
LIMIT 20Stop collecting
In the Github card, select the same Collector and click Disable integration, or run on the Collector host:
sudo /opt/utmstack-forwarder/utmstack_forwarder disable-integration github httpsThis also deletes the token file. Then delete the webhook in GitHub.
Troubleshooting
GitHub's Recent Deliveries tab shows the response for each delivery. Use it first: the Collector does not log rejected webhook requests.
| What Recent Deliveries shows | Likely cause | What to do |
|---|---|---|
| A timeout or "failed to connect" | Port 7020 is not reachable from the internet, or the integration is not enabled | Open the port to GitHub's hooks addresses. Check that the panel shows Currently: enabled · https · port 7020. On the Collector host, sudo ss -lntp lists the open TCP ports: look for 7020. |
| An SSL or certificate error | The certificate is self-signed, expired, missing intermediates, or issued for another name | Load a full-chain certificate from a public certificate authority for the name in the Payload URL (step 1). |
| 401 | The secret in GitHub does not match the token, or the signature header is missing | Copy the current token (step 2) into the webhook's Secret field and redeliver. After a disable and enable, a new token is created. |
| 404 | The Payload URL path is not /github | Fix the Payload URL. |
| 413 | The payload is larger than 8 MB, the most the Collector accepts | Select fewer event types if this repeats. |
| 503 | The Collector's queue was full for a moment | Click Redeliver in GitHub. If it repeats, see Forwarder Troubleshooting. |
204, but parsed fields are missing and errors is not empty | The webhook's content type is application/x-www-form-urlencoded | Set Content type to application/json. |