GitHub App Integration

Connect GitHub repositories to Nirmata for GitOps operations

Install and configure the Nirmata GitHub App to enable GitOps workflows and automated policy remediation. For an overview of what the integration does and why it improves security over PAT-based approaches, see GitHub App Integration Overview.

For a reference of what the app can and cannot access in your repositories, see GitHub App Permissions.

Installing GitHub App Integration

Follow these steps to connect your GitHub account to Nirmata:

Step 1: Navigate to Integrations

Log in to Nirmata Control Hub
Click on Settings in the left sidebar
Select Integrations
Locate the GitHub card in the Devops section

Integrations Page

Step 2: Connect GitHub App

Click the Connect button on the GitHub card
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

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
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
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
Click Install to authorize the connection

Step 4: Complete Setup

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

GitHub Connected

Managing GitHub App Integration

Viewing Connected Repositories

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

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

Modifying Repository Access

To add or remove repository access:

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

Disconnecting GitHub App

To remove the GitHub App integration:

Navigate to Settings → Integrations
Click Manage on the GitHub card
Click Disconnect or Remove
Confirm the removal

Alternatively, you can uninstall directly from GitHub:

Go to your GitHub organization Settings → Applications → Installed GitHub Apps
Find Nirmata and click Configure
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 Nirmata Control Hub
  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"
```text

**Prerequisites:**
- GitHub App installed and connected in Nirmata Control Hub
- `SERVICE_ACCOUNT_TOKEN` or `API_TOKEN` environment variable configured in your cluster
- No additional secrets required


### Example: Remediator with GitHub App

```yaml
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
```text


## 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:
   ```bash
   kubectl logs -n nirmata -l app.kubernetes.io/name=remediator-agent --tail=100

Verify your SERVICE_ACCOUNT_TOKEN or API_TOKEN is correctly configured

Remediator Agent Overview - Learn about AI-powered policy remediation
GitHub Authentication Guide - Detailed guide for using GitHub with AI agents
Integration Settings - All available integrations
GitOps Workflows - Using Git-based workflows in Nirmata

Support

Need help with GitHub App integration?

Nirmata Support: support@nirmata.com
Documentation: https://docs.nirmata.io
GitHub Apps Help: https://docs.github.com/en/apps
Community Forum: https://community.nirmata.io (if available)

GitHub App Integration Overview

What the Nirmata GitHub App integration does and why it improves GitOps security over PAT-based approaches.

GitHub App Permissions

What repository permissions the Nirmata GitHub App requests and what it can and cannot do.