> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keldyn.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub
> Connect GitHub to Keldyn so source-code access, change-management, authentication, and vulnerability-scanning evidence stays current automatically.
The GitHub integration connects a GitHub App installation to Keldyn's continuous-evidence engine. Once connected, Keldyn reads repository access, organization authentication settings, branch protections, pull-request reviews, and vulnerability-scanning results on a schedule and turns them into live evidence for the related controls.
Integrations and automated evidence are typically managed by workspace admins.
See [Evidence & audits](/evidence-and-audits) for how automated evidence fits
alongside manual evidence.
## What it's used for
Keldyn uses the data it reads from GitHub to keep evidence for source-code access, change management, secure development, and vulnerability management current. Each refresh updates the evidence and freshness status shown in the integration's **Controls covered** table.
The integration contributes evidence to these ISO 27001 controls:
| Control | Topic | Coverage |
| ----------------------------------------------------------- | ---------------------------------------------------- | -------- |
| **A.8.4** — Access to source code | Repository permissions and protected write paths | Full |
| **A.8.32** — Change management | Branch protections and pull-request approval history | Full |
| **A.8.8** — Management of technical vulnerabilities | Dependency and code-scanning posture and findings | Full |
| **A.5.15** — Access control | Repository-level access assignments | Partial |
| **A.8.5** — Secure authentication | Organization two-factor authentication requirement | Partial |
| **A.8.28** — Secure coding | Review and branch-protection requirements | Partial |
| **A.8.25** — Secure development life cycle | Pull-request reviews and static analysis | Partial |
| **A.8.29** — Security testing in development and acceptance | Dependency and static-analysis scanning | Partial |
**Full** coverage means the data is the artifact the control asks for.
**Partial** coverage means the data usefully contributes but does not, on its
own, replace everything the control requires. For example, pull-request
reviews support a secure development life cycle but do not prove that the
complete life cycle is defined and followed. Keldyn labels partial coverage
so it isn't mistaken for complete coverage.
## Before you begin
Installing the Keldyn GitHub App on an organization requires organization
owner approval. If you aren't an owner, GitHub may leave the installation
pending until an owner approves it.
During installation, choose whether Keldyn can read all repositories or only
selected repositories. Evidence only covers repositories included in the
GitHub App installation.
The GitHub App uses read-only repository and organization permissions.
Keldyn never changes repository settings, merges code, edits branches, or
modifies security alerts.
## Set up the integration
In the Keldyn web app, go to **Integrations** and select **GitHub**.
Select **Connect**. GitHub opens the Keldyn GitHub App installation flow.
Choose the organization and repositories to connect, review the requested
read-only access, and approve the installation.
Complete the GitHub authorization request. Keldyn uses it to verify that
your GitHub account can access the installation; it does not store your
user access token.
After GitHub returns you to Keldyn, select **Sync now** to pull evidence
immediately, or wait for the scheduled refresh. The **Controls covered** and
**Evidence sources** tables then show what was collected and how fresh it is.
From the integration detail page, **Controls covered** shows whether GitHub is
actively feeding each control and whether the control is satisfied.
**Evidence sources** shows each data fetch, the controls it covers, and its
freshness.
## What data Keldyn collects and why
Keldyn requests **read-only** access and collects only the data needed to build control evidence.
| Data collected | What it contains | Why Keldyn collects it | Refresh |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------- |
| **Repository collaborators** | Direct collaborators and their permission levels for each included repository | Shows who can access source code and what level of access they hold | Daily |
| **Organization 2FA requirement** | Whether the connected organization requires two-factor authentication | Contributes evidence for secure authentication | Daily |
| **Default-branch protection** | Protection settings for each repository's default branch, including review and status-check requirements | Shows how repositories restrict direct changes and gate merges | Daily |
| **Pull-request reviews** | Recent merged pull requests and their review and approval history | Provides a review trail for change management and secure development | Daily |
| **Dependabot alerts** | Whether Dependabot is enabled and the open dependency-vulnerability alerts for each repository | Evidences dependency scanning and active vulnerability findings | Hourly |
| **Code-scanning alerts** | Whether code scanning is enabled and the open static-analysis alerts for each repository | Evidences static security testing and active vulnerability findings | Hourly |
Keldyn does not collect pull-request titles. If Dependabot or code scanning is
disabled, Keldyn records that state as evidence instead of treating the sync
as a technical failure.
### Permissions
The Keldyn GitHub App requests these read-only permissions:
| Permission | Purpose |
| ------------------------------- | ------------------------------------------------------------- |
| **Repository metadata** | Discover included repositories and read collaborator access |
| **Repository administration** | Read collaborator permissions and default-branch protection |
| **Pull requests** | Read recent merged pull requests and their reviews |
| **Dependabot alerts** | Read dependency-scanning posture and alerts |
| **Code scanning alerts** | Read static-analysis posture and alerts |
| **Organization administration** | Read the organization's two-factor authentication requirement |
Keldyn stores the GitHub App installation ID and organization metadata. It mints short-lived installation tokens when it refreshes evidence and does not store a per-user GitHub token.
## Troubleshooting "Access required"
A control shows **Access required** when the GitHub App cannot read the matching data. Common causes include:
* The repository isn't included in the GitHub App installation.
* The installation is waiting for organization owner approval.
* A required read permission isn't granted to the GitHub App.
* Organization administration access isn't available for the 2FA requirement.
Open your [GitHub App installations](https://github.com/settings/installations), confirm the organization, repository access, and permissions, then run **Sync now** again. Controls not affected by the missing access continue to refresh normally.
If the installation was suspended or removed, Keldyn marks the connection **Reauth required**. Select **Reconnect** and complete the installation flow again.
## Keeping evidence current
Keldyn refreshes access, authentication, and change-management evidence daily. Dependabot and code-scanning evidence refreshes hourly. Evidence that hasn't refreshed within its expected cadence is marked **stale**, and failed pulls are marked **failed** so you can spot gaps. You can also trigger an immediate refresh at any time with **Sync now**.
## Next steps
Learn how automated integration evidence works alongside manual evidence and
audits.