Skip to main content

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

​
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. On the Integrations page, click Link repository.
FieldDescription
RepositoryThe GitHub repo (e.g. my-org/my-infra)
BranchThe branch to watch for PRs and auto-apply on merge (e.g. main)
PathThe folder inside the repo that contains this deployment’s manifests (e.g. apps/my-app)
ClusterWhich cluster to deploy to
Auto-syncWhether 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
  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.
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.

​
Auto-sync vs manual apply

ModeWhat happens on merge
Auto-sync enabled (default)Manifests are applied to the cluster automatically
Auto-sync disabledNiro 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
  • 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.
Last modified on June 12, 2026