GitHub Authentication Guide

Complete guide to GitHub authentication methods for Nirmata AI Agents

Overview

Nirmata AI Agents support multiple GitHub authentication methods to integrate with your GitHub repositories. This guide helps you choose the right authentication method and configure it properly.

Recommended Method: Use Nirmata’s GitHub App for the simplest, most secure integration. Install it once from Nirmata Control Hub, and it works across all GitOps operations.

Authentication Methods

Best for: Production environments and all GitOps operations

The Nirmata GitHub App method provides the simplest and most secure authentication. Simply install Nirmata’s GitHub App from the Control Hub UI - no need to create your own GitHub App or manage secrets.

Benefits

  • ✅ Zero Secret Management: No need to manage GitHub secrets in Kubernetes
  • ✅ Centralized Configuration: All credentials managed in NCH
  • ✅ Best Security: Short-lived tokens with fine-grained permissions
  • ✅ Automatic Rotation: Token refresh handled automatically
  • ✅ Enterprise Ready: Built for organizational use

Prerequisites

  1. Install GitHub App in NCH: Follow the GitHub App Integration guide to install Nirmata’s GitHub App
    • Navigate to Settings → Integrations in Nirmata Control Hub
    • Click Connect on the GitHub card
    • Authorize Nirmata to access your GitHub repositories
  2. Nirmata API Token: Your SERVICE_ACCOUNT_TOKEN or API_TOKEN must be configured in your cluster

Quick Setup

apiVersion: serviceagents.nirmata.io/v1alpha1
kind: ToolConfig
metadata:
  name: nirmata-github-tool
  namespace: nirmata
spec:
  type: github
  credentials:
    method: nirmata-app  # That's all you need!
  defaults:
    git:
      pullRequests:
        branchPrefix: "remediation-"
        titleTemplate: "remediator: Fix policy violations in %s"
        commitMessageTemplate: "Auto-fix: Remediate policy violations in %s"
        systemLabels:
          - "clusterName"
          - "namespace"
        customLabels:
          - "security"
          - "compliance"

How It Works

  1. You install Nirmata’s GitHub App once from the Control Hub UI
  2. The agent retrieves GitHub App credentials from NCH using your Nirmata API token
  3. No additional secrets or configuration required in your Kubernetes cluster
  4. Works for all GitOps operations including AI agents, policy management, and repository sync

2. Personal Access Token (PAT)

Best for: Development, testing, and proof-of-concept scenarios

Use PAT for quick testing or when GitHub App setup is not feasible.

Considerations

  • ⚠️ Long-lived Tokens: Less secure than GitHub Apps
  • ⚠️ User-bound: Tied to individual user accounts
  • ⚠️ Broader Permissions: Less granular permission control
  • ✅ Simple Setup: Quick to configure for testing

Quick Setup

Step 1: Create PAT Secret

kubectl create secret generic github-pat-token \
  --from-literal=token=YOUR_GITHUB_PAT \
  --namespace nirmata

Step 2: Create ToolConfig

apiVersion: serviceagents.nirmata.io/v1alpha1
kind: ToolConfig
metadata:
  name: github-pat-tool
  namespace: nirmata
spec:
  type: github
  credentials:
    method: pat
    pat:
      tokenSecretRef:
        name: github-pat-token
        namespace: nirmata
        key: token
  defaults:
    git:
      pullRequests:
        branchPrefix: "remediation-"
        titleTemplate: "[Auto-Remediation] Fix policy violations"
        commitMessageTemplate: "Auto-fix: Remediate policy violations"

Comparison Matrix

FeatureNirmata GitHub AppPersonal Access Token
Security✅ Excellent⚠️ Moderate
Token Lifetime1 hour (auto-refresh)Long-lived (requires manual rotation)
Setup Complexity✅ Simplest (one-click install)✅ Simple
Secret Management✅ Zero (managed by NCH)⚠️ Manual (K8s secrets)
Permission Control✅ Fine-grained⚠️ Broad (user-level)
Multi-Org Support✅ Yes (install per org)⚠️ User-bound
Audit Trail✅ Excellent (GitHub + NCH)⚠️ User-level only
Enterprise Ready✅ Yes⚠️ Limited
Credential Rotation✅ Automatic⚠️ Manual
Works for All GitOps✅ Yes⚠️ Requires separate PATs
Best Use CaseProduction & all environmentsQuick testing/POC only

Decision Guide

Choose Nirmata GitHub App When:

  • ✅ You’re using Nirmata Control Hub (highly recommended)
  • ✅ You want the simplest, most secure configuration
  • ✅ You need enterprise-grade security without overhead
  • ✅ You want zero secret management in Kubernetes
  • ✅ You’re deploying to production
  • ✅ You want one integration for all GitOps operations
  • ✅ You need automated credential rotation

Recommendation: Use Nirmata GitHub App for all environments (production, staging, development). It’s designed specifically for GitOps workflows and requires minimal configuration.

Choose Personal Access Token When:

  • ⚠️ You’re doing quick testing or proof-of-concept
  • ⚠️ You have simple, single-repository scenarios
  • ⚠️ You need to get started immediately without NCH setup
  • ⚠️ Your organization explicitly allows PAT usage for automation

Note: PATs are not recommended for production use due to security limitations and manual credential management requirements.

Complete Configuration Example

Step 1: Install GitHub App (One-Time Setup)

  1. Navigate to Nirmata Control Hub → Settings → Integrations
  2. Click Connect on the GitHub card
  3. Authorize Nirmata to access your repositories
  4. Done! The GitHub App is now available for all GitOps operations

Step 2: Create ToolConfig for AI Agents

apiVersion: serviceagents.nirmata.io/v1alpha1
kind: ToolConfig
metadata:
  name: nirmata-github-tool
  namespace: nirmata
spec:
  type: github
  credentials:
    method: nirmata-app  # Uses GitHub App from NCH
  defaults:
    git:
      pullRequests:
        branchPrefix: "remediation-"
        titleTemplate: "[Auto-Fix] {{.PolicyName}}"
        commitMessageTemplate: "Remediate: {{.PolicyName}} violations"
        systemLabels:
          - "clusterName"
          - "namespace"
        customLabels:
          - "automated"
          - "security"

Step 3: Use with Remediator Agent

apiVersion: serviceagents.nirmata.io/v1alpha1
kind: Remediator
metadata:
  name: remediator-prod
  namespace: nirmata
spec:
  environment:
    type: argoHub
  
  target:
    argoHubTarget:
      argoAppSelector:
        allApps: true
  
  remediation:
    llmConfigRef:
      name: remediator-agent-llm
      namespace: nirmata
    gitCredentials:
      name: nirmata-github-tool  # References Nirmata GitHub App
      namespace: nirmata
    triggers:
      - schedule:
          crontab: "0 */6 * * *"
    eventPolling:
      enabled: true
      intervalMinutes: 5
    actions:
      - type: CreatePR
        toolRef:
          name: nirmata-github-tool
          namespace: nirmata

Complete Workflow

  1. ✅ Install GitHub App in NCH (one-time, works for all GitOps operations)
  2. ✅ Create ToolConfig with method: nirmata-app
  3. ✅ Reference in Remediator - agent automatically uses GitHub App credentials
  4. ✅ Zero secret management - no GitHub secrets in Kubernetes
  5. ✅ Automatic token rotation - handled by NCH
  6. ✅ Audit trail - tracked in both GitHub and NCH

Pull Request Configuration

Understanding Labels

ToolConfig supports two types of PR labels:

System Labels (Dynamic)

Computed at runtime based on remediation context:

  • branch: Git branch being remediated
  • clusterName: Cluster where violations were found
  • appName: ArgoCD application name (if applicable)
  • namespace: Kubernetes namespace with violations

Note: System labels are only applied when data is available in the remediation context.

Custom Labels (Static)

Always added to every PR:

  • auto-remediation
  • security
  • compliance
  • Any custom labels you define

Example with All Label Types

defaults:
  git:
    pullRequests:
      branchPrefix: "fix/"
      titleTemplate: "[Auto-Fix] {{.PolicyName}}"
      commitMessageTemplate: "Remediate: {{.PolicyName}} violations"
      systemLabels:
        - "clusterName"
        - "namespace"
        - "appName"
      customLabels:
        - "automated"
        - "kyverno-policy"
        - "needs-review"

Best Practices

Security

  1. Use Nirmata GitHub App for production environments with NCH
  2. Rotate credentials regularly regardless of method
  3. Limit repository access to only what’s needed
  4. Use separate credentials for different environments
  5. Monitor audit logs for unexpected activity

Configuration

  1. Use descriptive names for ToolConfig resources
  2. Namespace isolation - keep configs in appropriate namespaces
  3. Document your setup - add comments explaining configuration choices
  4. Test in development before deploying to production

Maintenance

  1. Review permissions quarterly - ensure they’re still appropriate
  2. Update private keys on a schedule (every 90 days recommended)
  3. Monitor token usage through GitHub audit logs
  4. Keep documentation updated when changing configurations

Troubleshooting

GitHub App Not Connected

Symptom: ToolConfig fails with “GitHub App not configured”

Solutions:

  1. Verify GitHub App is installed in NCH:
    • Go to Settings → Integrations
    • Check if GitHub shows “Connected” status
  2. If not connected, click Connect and complete the authorization
  3. Ensure you selected the repositories where you want Nirmata to work

Authentication Failures

Symptom: Agent cannot authenticate with GitHub

Common Causes & Solutions:

For Nirmata GitHub App:

  1. Verify GitHub App is connected in NCH (Settings → Integrations)
  2. Check SERVICE_ACCOUNT_TOKEN or API_TOKEN is valid:
    kubectl get secret nirmata-api-token -n nirmata -o yaml
  3. Ensure the secret contains a valid, non-expired Nirmata API token
  4. Verify network connectivity from cluster to NCH
  5. Check that the GitHub App has access to the target repository

For PAT:

  1. Check token hasn’t expired
  2. Verify token has required scopes (repo, write:discussion)
  3. Ensure token secret exists in correct namespace:
    kubectl get secret github-pat-token -n nirmata

Cannot Create Pull Requests

Symptom: Authentication succeeds but PRs aren’t created

Solutions:

  1. Verify Nirmata GitHub App is installed on the target repository:
    • Go to GitHub → Settings → Applications → Installed GitHub Apps
    • Find “Nirmata” and check repository access
  2. Ensure the repository is not archived or read-only
  3. Check branch protection rules don’t block the app
  4. Review agent logs for detailed error messages:
    kubectl logs -n nirmata -l app.kubernetes.io/name=remediator-agent --tail=100

Missing Repository Access

Symptom: Nirmata cannot access a specific repository

Solutions:

  1. In GitHub, go to Settings → Applications → Installed GitHub Apps
  2. Click Configure next to Nirmata
  3. Add the repository or select “All repositories”
  4. Click Save
  5. Wait a few minutes for permissions to propagate

ToolConfig Method Not Working

Symptom: Error like “unsupported method: nirmata-app”

Solutions:

  1. Verify you’re using the latest Remediator Agent version
  2. Check that your Helm chart is up to date
  3. Ensure the agent has network access to NCH
  4. Review pod logs for version/compatibility information

Support

For additional help: