GitHub Integration

AIA automatically creates Pull Requests on GitHub with AI-generated fixes and detailed remediation instructions.

#How It Works

When an incident is detected and analyzed:

  1. Git Service clones your repository
  2. Creates a new branch: aia/incident-{uuid}
  3. Attempts to apply the AI-generated patch
  4. Commits changes (or saves failed patch)
  5. Pushes to GitHub
  6. Creates a Pull Request with:
    • Root cause analysis
    • AI fix prompt (for copy-paste to AI assistants)
    • Step-by-step manual instructions
    • Patch file (if auto-application failed)

#Setup

Step 1: Create GitHub Personal Access Token

  1. Go to GitHub Settings → Tokens
  2. Click "Generate new token (classic)"
  3. Name it (e.g., "AIA Bot")
  4. Select scope: repo (Full control of private repositories)
  5. Click "Generate token"
  6. Copy the token (starts with ghp_)

Step 2: Configure Environment

Add to .env:

Terminal
GITHUB_TOKEN=ghp_your_actual_token_here

Step 3: Configure Repository

Create aia.config.local.yaml:

Terminal
github: provider: "github" token: "PLACEHOLDER" # Read from .env owner: "your-github-username" repo: "your-repo-name" base_branch: "main"

Example:

  • Repo: https://github.com/johndoe/my-app
  • Set owner: "johndoe"
  • Set repo: "my-app"

#Pull Request Structure

Each PR created by AIA includes:

1. Title

Terminal
fix: resolve incident {incident-id}

2. Description

Root Cause: AI-generated explanation of what caused the error.

AI Fix Prompt: A detailed, copy-paste ready prompt for AI coding assistants (Cursor, GitHub Copilot, etc.).

Manual Steps: Step-by-step instructions for manual remediation.

Patch: If patch auto-application failed, the patch is saved as patch_failed_{timestamp}.diff in the commit.

3. Files Changed

  • If patch succeeded: The actual code changes
  • If patch failed: patch_failed_*.diff file with the patch content

4. Branch Name

Terminal
aia/incident-{uuid}

#Patch Handling

Automatic Application

The Git service attempts to automatically apply patches using git apply:

Terminal
git apply --ignore-space-change --ignore-whitespace patch.diff

Success Rate: ~40-60% (depends on AI patch quality)

When Patches Fail

If git apply fails:

  1. Patch is saved as patch_failed_{timestamp}.diff
  2. File is committed to the branch
  3. PR still created with:
    • AI fix prompt
    • Manual steps
    • Failed patch for reference

Users can:

  • Use the AI fix prompt with their preferred AI assistant
  • Follow manual steps
  • Manually apply the patch
  • Review and modify the suggested fix

#Token Permissions

The GitHub token needs:

| Permission | Required | Reason | | :--- | :--- | :--- | | repo | ✅ Yes | Clone, push, create PRs | | Contents | ✅ (included in repo) | Read/write code | | Pull Requests | ✅ (included in repo) | Create and manage PRs |

Note: Classic tokens with repo scope include all necessary permissions.

#Security Best Practices

Token Security

  • Never commit tokens to git
  • Store in .env (gitignored)
  • Use environment variables in production
  • Rotate tokens every 90 days

Repository Access

  • Token has access to all repos the user owns
  • For organizations, use a dedicated bot account
  • Limit token to specific repos if possible

Local Testing

  • Use aia.config.local.yaml (gitignored)
  • Keep production config with PLACEHOLDER values
  • Never commit real credentials

#Troubleshooting

"Repository not found"

  • Check owner and repo in config
  • Verify token has access to the repository
  • Ensure repository exists

"Permission denied"

  • Token needs repo scope
  • Check token hasn't expired
  • Verify token is correctly set in .env

"Failed to push"

  • Check branch doesn't already exist
  • Verify network connectivity
  • Ensure repository allows pushes

"PR creation failed"

  • Check GitHub API rate limits
  • Verify token permissions
  • Check repository settings allow PRs

#Example Workflow

  1. Incident detected → Agent receives error
  2. Autopsy analyzes → AI generates fix
  3. Git clones repo → git clone https://TOKEN@github.com/owner/repo.git
  4. Create branch → git checkout -b aia/incident-abc123
  5. Apply patch → git apply patch.diff (or save if fails)
  6. Commit → git commit -m "fix: resolve incident abc123"
  7. Push → git push origin aia/incident-abc123
  8. Create PR → GitHub API call with description
  9. Dashboard updates → Shows PR link

#Next Steps

OpenTelemetryNode.js Tutorial