GitHub

Connecting GitHub to KubeSense

Connect a GitHub organization and KubeSense records what happens in it as events: pushes, pull requests, comments and reviews, issues, releases, GitHub Actions runs, deployments, security alerts and more. When something breaks, you can see the merge, the failed run or the deploy that happened just before, on the same screen as your logs, traces and metrics.

Each organization is its own account under the GitHub tile. To add a second organization, run the connection again.

Prerequisites

• You are an owner of the GitHub organization, or a GitHub App manager in it. Only they can create the app in the organization. If you are not an owner, an owner has to approve the installation (see If you are not an owner).
• Your KubeSense can reach api.github.com over HTTPS.
• GitHub can reach KubeSense's webhook URL over HTTPS. Events arrive only through the webhook, so without it no GitHub events are recorded. See How activity arrives.

Connecting

1. Open Integrations and click the GitHub tile, then Add account.
2. In Organization to connect, type the name in github.com/<organization>. Leave it empty to connect your personal GitHub account instead. The Before you start panel lists every permission the app asks for.
3. Click Continue to GitHub.
4. GitHub opens and asks you to create the app. The name is prefilled as KubeSense. GitHub App names are unique across GitHub, so GitHub usually asks for another name, for example KubeSense acme. Then click Create GitHub App.
5. GitHub asks where to install the app. Choose All repositories or Only select repositories and pick them, then click Install. If you are not an owner, GitHub offers to send the owners a request instead (see If you are not an owner).
6. GitHub sends you back to KubeSense, which finishes the connection and opens the account page. The status shows Healthy.
7. Open the Webhook tab. If it says Webhook not set up, set the URL as described in Setting the webhook URL. No events are recorded until the webhook works.

You choose which repositories the app can see at install time. You can change that later with Manage on GitHub on the account page.

If you are not an owner

If you cannot install apps on the organization, GitHub sends a request to the organization's owners instead. An owner approves it on GitHub under the organization's Settings → GitHub Apps. Until then, the account shows Waiting for approval, with who asked and when. While the account page is open, KubeSense checks GitHub every 30 seconds and finishes the connection once an owner approves. Check now checks immediately.

If you stopped halfway

If the app was created but never installed, the account shows Not installed. Click Finish setup to go back to GitHub and pick repositories.

How activity arrives

GitHub events reach KubeSense only through a webhook: GitHub sends each event to KubeSense as it happens, usually within seconds. KubeSense creates every app with an active webhook subscribed to every event it records, so there is nothing to tick on GitHub. The webhook URL is the address you opened KubeSense from, followed by /api/integrations/github/webhook/<id>. If that address is one GitHub cannot deliver to, such as localhost or a private IP address, KubeSense leaves the webhook unset and you enter the URL yourself (see Setting the webhook URL). The Webhook tab on the account page shows whether deliveries are arriving.

Things to know:

• Events start when the webhook works. KubeSense does not backfill earlier activity, apart from the failed deliveries described below.
• GitHub must be able to reach the webhook URL. If KubeSense sits behind a firewall or VPN, allow inbound HTTPS from GitHub's webhook source IP ranges. GitHub lists them under hooks at https://api.github.com/meta, and the list changes over time.
• Failed deliveries are recovered. If a delivery fails, for example while KubeSense was down, KubeSense reads it from GitHub's delivery log and records it with its original time. GitHub keeps that log for about 3 days, so an outage longer than that loses the events in between.
• Without a working webhook, no GitHub events are recorded. The GitHub audit log is the exception: KubeSense reads it from GitHub's audit log API on its own schedule, with or without a webhook.

The Webhook tab

The Webhook tab shows one line that tells you where you stand:

When the webhook is not set up or has no recent deliveries, the tab also explains how to make the URL reachable and links to GitHub's list of webhook source IP ranges.

Once the webhook is set, the tab shows the URL GitHub delivers to and lists the events the app subscribes to, grouped by kind. If GitHub delivers somewhere other than the URL KubeSense saved, a warning tells you. To fix it, click Re-enable webhooks, check the URL, and click Save and set on GitHub.

Setting the webhook URL

If the tab says Webhook not set up, the address you connected from was one GitHub cannot deliver to, so KubeSense left the webhook unset. The tab opens the Webhook URL form with a note that says so. If you closed the form, click Enable webhooks to open it again. The form needs write access to Integrations.

1. Check the Webhook URL. It is prefilled with the webhook address under the address you are using KubeSense from. If the note says GitHub can't reach that address either, replace the start of it with the public https address of your KubeSense install, and keep the /api/integrations/github/webhook/... path. KubeSense refuses addresses GitHub cannot deliver to, such as localhost, private IP addresses, and names ending in .internal or .local.
2. Click Save and set on GitHub. KubeSense sets the URL and a fresh secret on the app.

If KubeSense is behind a firewall or VPN, also allow GitHub's webhook source IP ranges, as described in How activity arrives.

Choosing what is recorded

The Events & repositories tab controls what KubeSense records. By default everything in the organization is recorded. Switch off what you do not want.

The tab appears once the app is installed and the account is enabled. Changing it needs write access to Integrations (see Access control). Changes take effect when you click Save, and Cancel discards them.

Kinds of activity

Every kind has a switch, in three groups.

Code & collaboration

CI & delivery

Security & admin

Kinds tagged Enterprise Cloud exist only for organizations on GitHub Enterprise Cloud.

If you switch everything off, the tab warns that KubeSense records no GitHub events.

Repositories

Below the switches, the Repositories table decides where the kinds above are recorded. The kind switches apply to every repository listed.

Things to know:

• Branches apply only to the branch-based kinds: Pushes, Pull requests, Branches & tags, Actions runs, Actions jobs, Checks & statuses and Deployments. The other kinds are recorded from every branch.
• A repository that no row matches is not recorded. To record nothing from a repository, remove the row that covers it.
• The most specific row wins. If acme/* and acme/web both match, acme/web decides for that repository, so you can record a whole organization on every branch and narrow one repository to main.
• Add repository adds a row, and the bin button removes one.
• Reset to default appears once you have saved changes and goes back to recording everything in the organization.

The Repositories tab of the account marks each repository Synced or Not synced according to these rows. Use it to check that a repository you care about is covered.

The Events page

GitHub events appear under Events in the sidebar, together with any other custom events your organization sends to KubeSense.

The page has two parts:

• The query builder at the top. The filter box supports Basic and Advanced modes; switch between them with the toggle inside the filter box. Basic builds filters from field values you pick. Advanced takes a written query. Filter by cluster through this filter bar; there is no separate cluster selector on the page.
• The results below, as a list by default. Each row shows a severity bar, the source logo, the time, a title and a message. Runs and similar activity are shown once, in their latest state.

Click a row to open the details drawer. Overview shows the message and a table of tags. Event Attributes shows the full set of attributes. Use the arrows in the drawer header to step to the previous or next event.

Fields you can filter on

Attributes are searched with an @ in front, for example @vcs.ref.head.name (the branch), @vcs.ref.base.name (a pull request's target branch), @cicd.pipeline.name (the workflow), @cicd.pipeline.result, @vcs.change.id (the pull request or issue number) and @vcs.actor.is_bot. Open any event's Event Attributes to see the ones it carries.

Examples

In Advanced mode:

Quote values that contain slashes or dashes. In Basic mode, pick the same fields and values from the filter box.

Beyond the Events page

Events are a source in other places too:

• Data Explorer: chart or tabulate events, for example a count of failed runs per repository, grouped by workflow or branch. Numeric attributes such as duration_seconds can be averaged or sliced by percentile.
• Dashboards: add a panel over events, or mark events as vertical lines on existing charts with event overlays.
• KubeSense AI assistant and MCP: ask "what changed before this alert?" and the assistant can look at events as well as telemetry.

GitHub audit log

The audit log is optional and needs an organization on GitHub Enterprise Cloud. It records who changed members, teams, repositories, settings and security features in your organization. It is on the Events & repositories tab as the Audit log switch, under Security & admin.

The audit log is switched on like every other kind, but it stays idle until the app has permission to read it. GitHub does not grant that permission by default, and KubeSense never asks for it when creating the app.

Turning it on

1. On the Events & repositories tab, make sure Audit log is switched on. The status line under it tells you what is missing.
2. Open the link in that status, on GitHub. It goes straight to the app's permissions page.
3. Under Organization permissions, set Administration to Read-only and save.
4. An organization owner has to approve the permission change on GitHub. They receive a request from GitHub.
5. Within the hour, the status under the switch changes to Collecting.

What the status tells you

Where entries appear

Audit log entries are written to Logs, not to the Events page. Click View in Logs under the switch, or search Logs for source = github.

• KubeSense reads new entries every 5 minutes. The first read brings in the last 7 days.
• They are kept for the same time as your other logs.
• Each entry reads like a sentence, for example octocat team.add_member: team acme/web, user monalisa.
• Risky actions are marked WARN: deleted repositories, removed members and collaborators, transfers, changes to a repository's access, disabled security features, and branch-protection overrides. Everything else is INFO.
• The actor's IP address and location are never stored.

To narrow down, filter on the action, for example @action = "repo.destroy" for deleted repositories, or @actor = "octocat" for one person.

Managing the account

Clicking the GitHub tile opens the accounts page: every connected organization on the left, the selected one on the right. The header of an account offers:

The account page has four tabs, and opens on the first:

• Configuration: where the account points (GitHub.com), the GitHub App it connects through, when the connection was last tested, and who added it.
• Repositories: the repositories the app can see, read live from GitHub (the first 100, with the total), each marked Private, Synced or Not synced, a Manage on GitHub link to change which repositories are installed, and a GitHub App link to the app's page on GitHub.
• Webhook: how activity arrives. See How activity arrives.
• Events & repositories: what is recorded. See Choosing what is recorded.

The Webhook and Events & repositories tabs appear once the app is installed and the account is enabled.

Removing the connection

Click Remove and confirm. KubeSense stops recording and forgets the connection, but the GitHub App stays installed on GitHub. To delete it, open your organization's Settings → Developer settings → GitHub Apps on GitHub, select the app, and use Delete GitHub App under Advanced.

What the app can read

All permissions are read-only: repository metadata and contents, pull requests, issues, Actions, deployments, checks, commit statuses, merge queues, organization members, discussions, packages, Pages, Dependabot, code scanning and secret scanning alerts, and repository security advisories. Administration is not among them.

Access control

The Integrations RBAC module gates the page: Viewer sees accounts and their settings, Editor can connect, test, change what is recorded and remove. It is granted to the Admin role on upgrade; other roles are opened from Settings → Role Access.

Events shown on the Events page are governed by the Infrastructure module, and audit log entries by the same access as other logs.

Troubleshooting

No GitHub events at all

Events arrive only through the webhook. Open the Webhook tab:

• Webhook not set up: enter the public https address of your KubeSense install in the Webhook URL form on the tab, then click Save and set on GitHub (see Setting the webhook URL).
• Webhook: no recent deliveries while there is activity on GitHub: GitHub cannot reach the URL. If KubeSense is behind a firewall or VPN, allow GitHub's webhook source IP ranges, listed under hooks at https://api.github.com/meta. On GitHub, the app's Advanced settings list recent deliveries and the error each one got.

Activity from before the webhook worked is not backfilled, except failed deliveries from the last 3 days or so, which KubeSense recovers from GitHub's delivery log.

No events from one repository

Work through these in order:

1. Is the app installed on it? Open Manage on GitHub and check the repository is included. If the app is installed on Only select repositories, add it.
2. Does a row cover it? A repository that no row in the Repositories table matches is not recorded. Check the repository shows Synced on the Repositories tab.
3. Did a more specific row narrow it? acme/web overrides acme/* for that repository, including its branches.
4. Is the kind switched on? Branch-based kinds also need the branch to match, for example main.
5. Is the account paused or Not installed? Check the status chip.

Webhook deliveries are refused or not arriving

See the status table under The Webhook tab. Re-enable webhooks, then Save and set on GitHub, fixes a secret mismatch and a URL that has drifted from the one saved in KubeSense.

The audit log shows no entries

Check the status under the Audit log switch and follow What the status tells you. If it says Collecting but nothing shows in Logs, select All clusters and widen the time range: the first read brings in only the last 7 days.

The connection shows an error

Click Test. The error is shown on the account. If the app was deleted or uninstalled on GitHub, remove the account and connect it again.

"Could not connect GitHub" after returning from GitHub

The page shows the reason. The return link from GitHub works once, so if you reloaded it, start again from Integrations → GitHub → Add account. If KubeSense reports the organization is already connected, use the existing account, or remove it before connecting again. If GitHub created a second app in the meantime, delete the extra one in your organization's GitHub Apps settings.