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

---

### 3. Custom GitHub App

**Best for**: Organizations that must own the GitHub App themselves, or that run the agent without Nirmata Control Hub credentials

Use your own GitHub App when GitHub App security is required but installing Nirmata's App is not an option — for example a policy that all Apps be owned by your own organization, or an agent installed with `nirmata.auth=none`. You keep GitHub App benefits (short-lived tokens, fine-grained repository permissions) but manage the private key yourself.




github.com only

    All three authentication methods target github.com. The agent has no setting for a GitHub Enterprise Server API endpoint, so a custom GitHub App must be installed on github.com — it cannot authenticate against a self-hosted GHES instance.




#### Considerations

- ✅ **Short-lived Tokens**: Installation access tokens, same as the Nirmata App
- ✅ **Fine-grained Permissions**: Scoped per repository, not per user
- ✅ **No Control Hub Dependency**: Works with `nirmata.auth=none`
- ⚠️ **You Manage the Private Key**: Stored as a Kubernetes Secret and rotated by you
- ⚠️ **Requires `github.com` Reachability**: The agent mints tokens against the GitHub API

#### Prerequisites

1. Create a GitHub App in your organization and generate a private key (`.pem`).
2. Grant it repository permissions covering what the agent does: read and write **Contents** (commit the fix) and **Pull requests** (open and comment on PRs), read **Metadata**, and write **Checks** so the agent can report its [CI checks](../configuration/#ci-checks). Add write **Issues** only if you configure the `CreateIssue` action.
3. Install the App on the repositories the agent should remediate.
4. Note the **App ID** from the App's settings page.

#### Quick Setup

**Step 1: Create the private key Secret**

```bash
kubectl create secret generic github-app-private-key \
  --from-file=private-key.pem=/path/to/your-app.private-key.pem \
  --namespace nirmata

apiVersion: serviceagents.nirmata.io/v1alpha1
kind: ToolConfig
metadata:
  name: github-app-tool
  namespace: nirmata
spec:
  type: github
  credentials:
    method: app
    app:
      appId: 123456
      # installationId: 78901234   # optional — auto-discovered when omitted
      privateKeySecretRef:
        name: github-app-private-key
        key: private-key.pem
  defaults:
    git:
      pullRequests:
        branchPrefix: "remediation-"
        systemLabels:
          - "clusterName"
          - "namespace"

tool:
  credentials:
    method: app
    app:
      appId: 123456
      privateKeySecret:
        name: github-app-private-key
        key: private-key.pem

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:
    argoHub:
      appSelector:
        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