> ## 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.

# Set Up GitOps

> Link a GitHub repo to a cluster for PR-based deploys with AI manifest review and auto-apply on merge.

## Overview

Niro's GitOps integration uses a **GitHub App** to:

1. Receive webhooks when PRs are opened against your linked repo
2. Run rule-based manifest validation (always authoritative) and AI review (advisory)
3. Post findings as PR comments and a GitHub check run
4. Automatically apply the manifests to your cluster when the PR is merged

All traffic is initiated from Niro's servers to GitHub — the cluster agent doesn't need GitHub access.

## Prerequisites

* A cluster connected to Niro with the apply capability enabled (`NIRO_ENABLE_APPLY=1`)
* A GitHub account with permission to create a GitHub App in your personal account or organization
* A GitHub repo containing (or where you'll commit) your Kubernetes manifests

## Step 1: Create the GitHub App

Go to **Integrations** → **GitHub** in the Niro dashboard and click **Create and install GitHub App**.

This opens GitHub's **App manifest flow** in a new tab. GitHub generates a new App with the right permissions and webhook URL pre-configured. Click **Create GitHub App** on the GitHub page.

After creation, GitHub redirects back to the Niro dashboard. The App's private key and webhook secret are stored securely — you don't need to manage them.

<Note>
  You only need to create the GitHub App once per Niro organization. After that, you can install it in as many GitHub accounts/orgs as you need and link as many repos as you like.
</Note>

## Step 2: Install the GitHub App

After the App is created, you need to install it in the GitHub account or organization that owns the repo you want to link.

From the Integrations page, click **Install App**. GitHub asks you which account to install it on and which repositories to grant access to. Select at least the repo(s) you want to use with Niro.

## Step 3: Link a repo to a cluster

On the Integrations page, click **Link repository**.

| Field          | Description                                                                               |
| -------------- | ----------------------------------------------------------------------------------------- |
| **Repository** | The GitHub repo (e.g. `my-org/my-infra`)                                                  |
| **Branch**     | The branch to watch for PRs and auto-apply on merge (e.g. `main`)                         |
| **Path**       | The folder inside the repo that contains this deployment's manifests (e.g. `apps/my-app`) |
| **Cluster**    | Which cluster to deploy to                                                                |
| **Auto-sync**  | Whether to automatically apply on merge (recommended: on)                                 |

Click **Link**. Niro creates the repo link and registers the webhook.

## Step 4: Open a PR

Push a branch with Kubernetes manifest changes to your repo and open a PR against the linked branch.

Niro receives the webhook and:

1. Runs **rule-based validation** — checks for common Kubernetes misconfigurations (missing probes, missing resource limits, mutable image tags, etc.) per the [policy rules](/features/policies)
2. Optionally runs **AI manifest review** — an LLM reviews the manifests for common issues and suggestions
3. Posts a single comment on the PR with all findings grouped by deployment
4. Creates a GitHub **check run** (shown in the PR's checks section)

Findings are advisory — they don't block the PR from being merged.

### AI review

The AI review is available on Pro+ plans. It runs after the rule-based checks and posts an additional comment with:

* Summary of changes
* Identified potential issues
* Suggested improvements

If the AI review fails (e.g. the LLM provider is unavailable), the check run shows "AI review unavailable" and doesn't block the PR.

## Step 5: Merge and auto-apply

When the PR is merged:

1. Niro receives the merge webhook
2. Niro sends an apply command to the cluster's agent
3. The agent applies the manifests from the PR
4. The agent reports per-object results
5. Niro updates the GitHub **Deployment status** on the merge commit with the result

If you delete a folder from the repo (removing a deployment), Niro instructs the agent to remove only the objects it previously applied.

<Check>
  After merging, look for the deployment status badge on the commit in GitHub. It links back to the deployment in Niro with the full apply result.
</Check>

## Auto-sync vs manual apply

| Mode                            | What happens on merge                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| **Auto-sync enabled** (default) | Manifests are applied to the cluster automatically                                         |
| **Auto-sync disabled**          | Niro validates the PR but does not apply — you trigger applies manually from the dashboard |

You can toggle auto-sync per repo link in the Integrations page.

## Drift detection

With a linked repo, Niro can detect **drift**: when the live cluster state diverges from the repo's desired state. Drift can happen if someone applies changes directly with `kubectl` instead of through the GitOps flow.

When drift is detected:

* A `drift_detected` incident fires in [Alerts](/features/alerts)
* The deployment detail page shows a diff between live state and repo state
* If auto-sync is enabled, Niro re-applies the repo state to resolve the drift

## Rollback

To roll back a deployment via GitOps:

1. Open the deployment in the Niro dashboard
2. Click **Rollback** — Niro opens a PR with the manifests from the previous successful deploy
3. Merge the PR to apply the rollback

## Troubleshooting

### PR comments aren't appearing

Check that:

* The GitHub App is installed in the repo's owner account
* The webhook is registered — check Integrations → GitHub → webhook recent deliveries
* The linked branch matches the target branch of your PR

### Apply didn't run after merge

Check that:

* Auto-sync is enabled for this repo link
* The agent has the apply capability (`NIRO_ENABLE_APPLY=1`)
* The agent is online — check the cluster heartbeat in the Fleet view

### Check run is stuck on "Pending"

The webhook background job may be queued. Check the cluster status and try re-delivering the webhook from the GitHub App's advanced settings.

## Related

* [Connect a Cluster](/guides/connect-cluster) — enroll a cluster and enable the apply capability
* [Policies](/features/policies) — rules evaluated on every PR
* [AI Incident Investigator](/features/ai-investigation) — investigate incidents with AI after they're detected
* [Alerts](/features/alerts) — get notified when drift or deployment failures occur