# GitHub

The GitHub integration connects Interlynk to your GitHub repositories, enabling automated SBOM processing triggered by repository events.

***

## Purpose

* Automatically ingest SBOMs when code is pushed or pull requests are created/merged.
* Map repository branches to Interlynk environments using environment rules.
* Enable PR comments with SBOM analysis results.

## Setup Steps

### GitHub App (Recommended)

Interlynk uses a GitHub App for OAuth-based authentication. This provides fine-grained repository access without personal access tokens.

1. Navigate to **Settings > Organization > Integrations**.
2. Click **GitHub**.
3. You will be redirected to GitHub to authorize the Interlynk GitHub App.
4. Select the **repositories** or **organization** to grant access to.
5. Complete the authorization. You will be redirected back to Interlynk.
6. The integration displays your GitHub **username** and connection status.

### Repository Selection

After authorization, configure which repositories trigger SBOM processing:

* Set up **environment rules** (see [Environment Rules](https://docs.interlynk.io/administration/environment-rules)) to map branches to Interlynk environments.
* Configure webhook triggers for the events you want to respond to.

## Supported Events

| Event                    | Trigger                               |
| ------------------------ | ------------------------------------- |
| `push`                   | Code pushed to a branch               |
| `pull_request` (created) | New pull request opened               |
| `pull_request` (merged)  | Pull request merged                   |
| `pull_request` (updated) | Pull request updated with new commits |

## Required Permissions

The GitHub App requests the following permissions:

| Scope                      | Purpose                                |
| -------------------------- | -------------------------------------- |
| Repository contents (read) | Read SBOM files from repositories      |
| Pull requests (read/write) | Post PR comments with analysis results |
| Webhooks (read/write)      | Receive push and PR events             |

## Security Notes

* The OAuth connection uses token refresh — tokens are automatically re-issued when they expire.
* Interlynk stores only the OAuth token, not your GitHub password.
* You can revoke access at any time from GitHub's **Settings > Applications > Authorized GitHub Apps**.

## Troubleshooting

| Issue                       | Cause                                                  | Resolution                                                 |
| --------------------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
| Webhook events not received | GitHub App not installed on the repository             | Verify the app is installed and the repository is selected |
| PR comments not appearing   | Missing pull request write permission                  | Re-authorize the GitHub App with the correct permissions   |
| OAuth token expired         | Token refresh failed                                   | Disconnect and reconnect the GitHub integration            |
| Wrong repositories visible  | App installed at organization level with limited repos | Update repository access in GitHub App settings            |