GitHub App Integration

Connect GitHub repositories to Nirmata for GitOps operations

Overview

The GitHub App Integration enables seamless integration between Nirmata and your GitHub repositories. By installing Nirmata’s GitHub App, you can enable GitOps workflows, automated policy remediation, and other Git-based operations across your Nirmata platform.

This integration is used by:

  • AI Agents (e.g., Remediator Agent) for creating pull requests with policy fixes
  • GitOps workflows for repository synchronization
  • Policy management for Git-based policy storage
  • Compliance operations for tracking and remediating violations

Benefits

  • ✅ One-Click Installation: Install Nirmata’s GitHub App directly from the UI
  • ✅ Enhanced Security: Uses short-lived tokens with fine-grained permissions
  • ✅ Centralized Management: Manage GitHub integration through Nirmata Control Hub
  • ✅ Enterprise Ready: Designed for organizational use with proper access control
  • ✅ Audit Trail: Complete tracking and logging of all GitHub operations
  • ✅ Multi-Organization Support: Install across multiple GitHub organizations
  • ✅ No Secret Management: No need to manage tokens or keys manually

Installing GitHub App Integration

Follow these steps to connect your GitHub account to Nirmata:

Step 1: Navigate to Integrations

  1. Log in to Nirmata Control Hub
  2. Click on Settings in the left sidebar
  3. Select Integrations
  4. Locate the GitHub card in the Devops section

Integrations Page

Step 2: Connect GitHub App

  1. Click the Connect button on the GitHub card
  2. You will be redirected to GitHub’s authorization page

GitHub Connect Button

Step 3: Install Nirmata GitHub App

On the GitHub authorization page, you’ll see:

Install Nirmata GitHub App

  1. Select Account: Choose the GitHub account or organization where you want to install the app

    • You’ll see your personal account and any organizations you have admin access to

  2. Select Repositories: Choose which repositories Nirmata can access:

    • All repositories: Grant access to all current and future repositories (recommended for full GitOps workflows)
    • Only select repositories: Choose specific repositories for more granular control

  3. Review Permissions: The Nirmata GitHub App requests the following permissions:

    • ✅ Read access to metadata: Required by GitHub (mandatory)
    • ✅ Read and write access to code, issues, and pull requests: Enables Nirmata to:
      • Create branches and commits
      • Open pull requests for policy remediations
      • Create and manage issues
      • Read repository contents

  4. Click Install to authorize the connection

Step 4: Complete Setup

  1. After clicking Install, you’ll be redirected back to Nirmata Control Hub
  2. The GitHub integration will now show as Connected
  3. You can now use this integration across all Nirmata features that require GitHub access

GitHub Connected

GitHub App Permissions Explained

The Nirmata GitHub App requests the following permissions to enable GitOps workflows:

Repository Permissions

PermissionAccess LevelPurpose
MetadataReadRequired by GitHub (mandatory for all apps)
ContentsRead & WriteCreate and modify files, branches, and commits
Pull RequestsRead & WriteCreate, update, and merge pull requests
IssuesRead & WriteCreate and manage issues for tracking

What Nirmata Can Do

With these permissions, Nirmata can:

  • ✅ Read repository contents and metadata
  • ✅ Create branches for policy fixes
  • ✅ Commit changes to branches
  • ✅ Open pull requests with automated fixes
  • ✅ Add comments to pull requests
  • ✅ Create issues for violations or notifications
  • ✅ Read and respond to PR comments

What Nirmata Cannot Do

The app cannot:

  • ❌ Delete repositories
  • ❌ Modify repository settings
  • ❌ Change collaborator permissions
  • ❌ Force push or delete branches (unless branch protection allows)
  • ❌ Merge PRs without proper approvals (if branch protection is enabled)
  • ❌ Access repositories not explicitly granted during installation

Managing GitHub App Integration

Viewing Connected Repositories

After installation, you can view and manage the connected repositories:

  1. Navigate to Settings → Integrations
  2. Click Manage on the GitHub card
  3. You’ll see the list of connected repositories and installation details

Modifying Repository Access

To add or remove repository access:

  1. Navigate to Settings → Integrations
  2. Click Manage on the GitHub card
  3. Click Configure or go directly to your GitHub settings
  4. In GitHub, navigate to Settings → Applications → Installed GitHub Apps
  5. Find Nirmata and click Configure
  6. Modify repository access as needed
  7. Click Save

Disconnecting GitHub App

To remove the GitHub App integration:

  1. Navigate to Settings → Integrations
  2. Click Manage on the GitHub card
  3. Click Disconnect or Remove
  4. Confirm the removal

Alternatively, you can uninstall directly from GitHub:

  1. Go to your GitHub organization Settings → Applications → Installed GitHub Apps
  2. Find Nirmata and click Configure
  3. Scroll down and click Uninstall

Using GitHub App with Nirmata Features

Once the GitHub App is connected, it can be used across various Nirmata features:

AI Agents (Remediator Agent)

The Remediator Agent uses the GitHub App to create pull requests with policy fixes:

apiVersion: serviceagents.nirmata.io/v1alpha1
kind: ToolConfig
metadata:
  name: nirmata-github-tool
  namespace: nirmata
spec:
  type: github
  credentials:
    method: nirmata-app  # Uses GitHub App configured in NCH
  defaults:
    git:
      pullRequests:
        branchPrefix: "remediation-"
        titleTemplate: "remediator: Fix policy violations in %s"
        commitMessageTemplate: "Auto-fix: Remediate policy violations in %s"
        systemLabels:
          - "branch"
          - "clusterName"
          - "appName"
          - "namespace"
        customLabels:
          - "security"
          - "compliance"

Prerequisites:

  • GitHub App installed and connected in NCH
  • SERVICE_ACCOUNT_TOKEN or API_TOKEN environment variable configured in your cluster
  • No additional secrets required

Example: Remediator with GitHub App

apiVersion: serviceagents.nirmata.io/v1alpha1
kind: Remediator
metadata:
  name: remediator-sample
  namespace: nirmata
spec:
  environment:
    type: argoHub
  
  target:
    argoHubTarget:
      argoAppSelector:
        allApps: true
  
  remediation:
    llmConfigRef:
      name: remediator-agent-llm
      namespace: nirmata
    gitCredentials:
      name: nirmata-github-tool  # Reference to your ToolConfig
      namespace: nirmata
    triggers:
      - schedule:
          crontab: "0 */6 * * *"
    actions:
      - type: CreatePR
        toolRef:
          name: nirmata-github-tool  # Reference to your ToolConfig
          namespace: nirmata

Troubleshooting

Cannot Connect to GitHub

Problem: The “Connect” button doesn’t redirect to GitHub or shows an error

Solutions:

  1. Ensure you’re logged into GitHub in the same browser
  2. Check that pop-ups are not blocked in your browser
  3. Verify you have admin access to the GitHub organization where you want to install
  4. Clear browser cache and cookies, then try again

Missing Repository Access

Problem: Nirmata cannot access a specific repository

Solutions:

  1. Verify the repository is included in the GitHub App installation:
    • Go to GitHub → Settings → Applications → Installed GitHub Apps
    • Click Configure next to Nirmata
    • Check if the repository is listed or “All repositories” is selected
  2. If missing, add the repository:
    • Click Configure next to Nirmata
    • Select the repository from the dropdown
    • Click Save

Pull Requests Not Being Created

Problem: AI agents or GitOps workflows can’t create pull requests

Solutions:

  1. Verify the GitHub App is installed on the target repository (see “Missing Repository Access” above)
  2. Check that the repository is not archived or read-only
  3. Ensure branch protection rules don’t prevent the app from pushing
  4. Review the application logs for detailed error messages:
    kubectl logs -n nirmata -l app.kubernetes.io/name=remediator-agent --tail=100
  5. Verify your SERVICE_ACCOUNT_TOKEN or API_TOKEN is correctly configured

Frequently Asked Questions

Do I need to create my own GitHub App?

No. Nirmata provides a ready-to-use GitHub App that you can install directly from the Nirmata Control Hub interface. Simply click “Connect” and authorize the app.

Can I use the GitHub App with multiple organizations?

Yes. You can install the Nirmata GitHub App on multiple GitHub organizations. Simply repeat the connection process for each organization you want to integrate.

What happens if I disconnect the GitHub App?

Disconnecting will:

  • Stop all automated operations (PRs, commits, etc.)
  • Prevent AI agents from creating pull requests
  • Disable GitOps sync operations
  • Close the integration in Nirmata Control Hub

Your existing pull requests and issues will remain in GitHub.

Can I limit which repositories Nirmata accesses?

Yes. During installation, you can choose “Only select repositories” and pick specific repositories. You can modify this selection anytime from GitHub’s app settings.

Support

Need help with GitHub App integration?