GitHub Authentication Guide

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

#### How It Works

1. You install Nirmata's GitHub App once from the Control Hub UI
2. The agent retrieves GitHub App credentials from Nirmata Control Hub 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**

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

**Step 2: Create ToolConfig**

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

---

## Comparison Matrix

| Feature | Nirmata GitHub App | Personal Access Token |
|---------|-------------------|-----------------------|
| **Security** | ✅ Excellent | ⚠️ Moderate |
| **Token Lifetime** | 1 hour (auto-refresh) | Long-lived (requires manual rotation) |
| **Setup Complexity** | ✅ Simplest (one-click install) | ✅ Simple |
| **Secret Management** | ✅ Zero (managed by Nirmata Control Hub) | ⚠️ Manual (K8s secrets) |
| **Permission Control** | ✅ Fine-grained | ⚠️ Broad (user-level) |
| **Multi-Org Support** | ✅ Yes (install per org) | ⚠️ User-bound |
| **Audit Trail** | ✅ Excellent (GitHub + Nirmata Control Hub) | ⚠️ User-level only |
| **Enterprise Ready** | ✅ Yes | ⚠️ Limited |
| **Credential Rotation** | ✅ Automatic | ⚠️ Manual |
| **Works for All GitOps** | ✅ Yes | ⚠️ Requires separate PATs |
| **Best Use Case** | Production & all environments | Quick 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 Nirmata Control Hub 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

```yaml
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 Nirmata Control Hub
  defaults:
    git:
      pullRequests:
        branchPrefix: "remediation-"
        titleTemplate: "[Auto-Fix] {{.PolicyName}}"
        commitMessageTemplate: "Remediate: {{.PolicyName}} violations"
        systemLabels:
          - "clusterName"
          - "namespace"
        customLabels:
          - "automated"
          - "security"
```text

### Step 3: Use with Remediator Agent

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

### Complete Workflow

1. ✅ **Install GitHub App** in Nirmata Control Hub (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 Nirmata Control Hub
6. ✅ **Audit trail** - tracked in both GitHub and Nirmata Control Hub

---

## 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

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

---

## Best Practices

### Security

1. **Use Nirmata GitHub App** for production environments with Nirmata Control Hub
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 Nirmata Control Hub:
   - 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 Nirmata Control Hub (Settings → Integrations)
2. Check your Nirmata Control Hub Service Account token (`SERVICE_ACCOUNT_TOKEN`) or API token (`API_TOKEN`) is valid:
   ```bash
   kubectl get secret nirmata-service-account-token -n nirmata -o yaml