Skip to content
AletheiaAletheiaAletheia docs

Connect GitHub

Aletheia connects to GitHub as a GitHub App, installed by an organization owner. An App installation is scoped to the repositories you select and can be revoked from GitHub at any time, independently of Aletheia.

Installing

Section titled “Installing”
  1. Go to Administration → Integrations → Source control (/admin/integrations/source-control).
  2. Start the GitHub installation. Aletheia hands you off to GitHub.
  3. On GitHub, choose the account or organization, then choose all repositories or a specific list.
  4. GitHub returns you to the same screen, and the connection appears as connected.

You need permission to manage integrations in Aletheia, and permission to install an App on the GitHub side. They are usually different people, which is why the flow survives the round trip.

What it reads

Section titled “What it reads”
Permission Why
Repository contents (read) Find Terraform and OpenTofu roots, and index the code that declares resources
Pull requests (read) Track pull requests that touch infrastructure code
Metadata (read) List the repositories available to the installation

All of it is read. Aletheia does not push commits, open pull requests, or change repository settings anywhere in the shipped product.

Choosing repositories

Section titled “Choosing repositories”

Installing the App makes repositories available; it does not put them in scope. After connecting, you select which of the available repositories Aletheia should actually index.

Selecting fewer is always safe. An unselected repository is not read, and the only consequence is that resources declared there stay unknown rather than being matched.

Webhooks

Section titled “Webhooks”

The App delivers webhooks for repository and pull-request events. Every delivery is verified against the shared secret before it is processed, and a replayed delivery is recognised and ignored.

Webhooks keep the picture current between syncs. If deliveries stop, a manual sync from the connection screen re-reads the repositories directly.

Revoking

Section titled “Revoking”

Uninstall the App from GitHub, or delete the connection in Aletheia. Either stops all reads. Deleting the connection in Aletheia leaves the discovered inventory in place — it is AWS data, and it did not come from GitHub.

Where to go next

Section titled “Where to go next”