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 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 |
| 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 |
PR review behavior
When a PR is opened against a linked repo branch:
- Webhook received — Niro immediately returns
202 Accepted and enqueues the job
- Background job runs — parses manifests, runs policy checks, optionally runs AI review
- PR comment posted — a single comment per deployment lists all findings
- 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 |
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:
- Go to Integrations → GitHub
- 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.
Last modified on June 12, 2026
