> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niro.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration

> Connect Niro to GitHub for PR-based deployments, AI manifest review, and auto-apply on merge.

## Overview

The Niro GitHub integration uses a **GitHub App** to connect your repositories to your clusters. Once connected, you get:

* Automatic manifest validation when PRs are opened
* Advisory AI review posted as PR comments
* Auto-apply to the cluster on merge
* GitHub Deployment statuses on commits
* Image Automation: auto-PR when new image versions are published

## How it works

Niro creates a **GitHub App** on your behalf (via GitHub's App manifest flow). This App:

* Installs in your GitHub account or organization
* Receives webhooks for PR and push events on repos you've granted access to
* Posts review comments and check runs to PRs
* Creates GitHub Deployment statuses when applies complete
* (For image automation) reads package/release tags from the registry

The App's private key and webhook secret are stored securely — you don't need to manage them.

## Setup

See [Set Up GitOps](/guides/gitops) for the full step-by-step walkthrough.

## GitHub App permissions

The Niro GitHub App requests the following permissions:

| Permission      | Scope        | Reason                                            |
| --------------- | ------------ | ------------------------------------------------- |
| `contents`      | Read & write | Read manifests, commit builder output, create PRs |
| `pull_requests` | Read & write | Post review comments, update PR status            |
| `checks`        | Read & write | Create check runs for policy findings             |
| `deployments`   | Read & write | Create Deployment statuses on merge commits       |
| `metadata`      | Read         | Required by GitHub for all Apps                   |

For Image Automation:

| Permission | Scope | Reason                      |
| ---------- | ----- | --------------------------- |
| `packages` | Read  | Read package tags from GHCR |

## Webhook events

Niro subscribes to the following GitHub webhook events:

| Event                                          | What Niro does                                              |
| ---------------------------------------------- | ----------------------------------------------------------- |
| `pull_request` (opened, synchronize, reopened) | Run policy checks + AI review, post comment + check run     |
| `pull_request` (closed, merged)                | If merged: apply (or delete) manifests to cluster           |
| `push` (to linked branch)                      | Update deployment status, detect drift                      |
| `registry_package` (published)                 | Evaluate against image policies, open bump PR if applicable |

Webhook delivery is idempotent — Niro deduplicates by GitHub's delivery ID to prevent double-processing.

## PR review behavior

When a PR is opened against a linked repo branch:

1. **Webhook received** — Niro immediately returns `202 Accepted` and enqueues the job
2. **Background job runs** — parses manifests, runs policy checks, optionally runs AI review
3. **PR comment posted** — a single comment per deployment lists all findings
4. **Check run created** — shows pass/warn/fail in the PR checks section

The PR comment is updated (not duplicated) if you push more commits to the same PR.

### Check run states

| State          | Meaning                                            |
| -------------- | -------------------------------------------------- |
| ✅ **Pass**     | No high-severity findings                          |
| ⚠️ **Neutral** | Medium or low severity findings only               |
| ✅ (with note)  | AI review unavailable — rule-based check still ran |

Check runs are **never blocking** — they don't prevent merging regardless of findings.

## Repo link settings

Each repo link has the following settings (editable on the Integrations page):

| Setting        | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| **Repository** | The GitHub repo                                                  |
| **Branch**     | The branch to watch (e.g. `main`)                                |
| **Path**       | The folder containing this deployment's manifests                |
| **Cluster**    | The target cluster                                               |
| **Namespace**  | The target namespace (used for namespace-mismatch policy checks) |
| **Auto-sync**  | Whether to apply automatically on merge                          |

## Multiple repos and clusters

You can link:

* Multiple repos to the same cluster
* The same repo to multiple clusters (e.g. `deploy/production` → prod cluster, `deploy/staging` → staging cluster)
* Multiple folders in the same repo to different clusters or deployments

Each folder in the repo is an independent Niro deployment. Niro tracks which manifests it applied from each folder.

## Uninstalling

To remove the GitHub integration:

1. Go to Integrations → GitHub
2. Click **Uninstall App** — this removes all repo links and the App installation from GitHub

If you only want to remove a specific repo link, click the three-dot menu next to the link and select **Remove**.

## Related

* [Set Up GitOps](/guides/gitops) — full walkthrough
* [Image Automation](/guides/image-automation) — auto-PR on new image versions
* [Policies](/features/policies) — rules evaluated on PRs
* [Deployments](/concepts/deployments) — how Niro manages workloads