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

SettingValue
Card on the Integrations pageGithub (category DevOps)
Data typegithub
Listener on the CollectorHTTPS on port 7020, path /github, listening on all addresses
AuthenticationHMAC signature (a hash of each request made with a shared secret) in the X-Hub-Signature-256 header
Format UTMStack expectsGitHub's JSON webhook payloads (content type application/json)
Parsing pipelinegithub/github.yaml. The Filters button in the drawer opens it.
Detection rules13 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 hooks list of https://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.write permission 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. 1

    Open the integration

    In UTMStack, go to Configure > Integrations and open the Github card.

    GitHub setup guide in UTMStack: Enable this integration remotely with Protocol HTTPS, Port 7020, HMAC signature authentication, Path /github and Signature header X-Hub-Signature-256
  2. 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 /github and Signature header X-Hub-Signature-256. Unlike syslog integrations, the HTTPS listener uses the port you type here.

  3. 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 https

The 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 fieldValue
Payload URLhttps://<collector-domain>:7020/github
Content typeapplication/json
SecretThe token from step 2
SSL verificationKeep it enabled
Which eventsSend 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

  1. In GitHub, open the webhook and its Recent Deliveries tab. The ping delivery should show the response code 204, which means the Collector accepted it.

  2. In the Github drawer, click View logs. Log Explorer opens on the logs data set with the github data type for the last 24 hours. You can also open Log Explorer and choose the data type yourself.

  3. Expand an event. The Parsed fields view should show the webhook fields under log., and the errors field should be empty.

  4. Within about 20 minutes, a source named github appears 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 20

Stop 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 https

This 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 showsLikely causeWhat to do
A timeout or "failed to connect"Port 7020 is not reachable from the internet, or the integration is not enabledOpen 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 errorThe certificate is self-signed, expired, missing intermediates, or issued for another nameLoad a full-chain certificate from a public certificate authority for the name in the Payload URL (step 1).
401The secret in GitHub does not match the token, or the signature header is missingCopy the current token (step 2) into the webhook's Secret field and redeliver. After a disable and enable, a new token is created.
404The Payload URL path is not /githubFix the Payload URL.
413The payload is larger than 8 MB, the most the Collector acceptsSelect fewer event types if this repeats.
503The Collector's queue was full for a momentClick Redeliver in GitHub. If it repeats, see Forwarder Troubleshooting.
204, but parsed fields are missing and errors is not emptyThe webhook's content type is application/x-www-form-urlencodedSet Content type to application/json.