aieng-bot - Setup Guide¶

Overview¶

aieng-bot is an AI-powered tool that autonomously fixes CI failures, resolves merge conflicts, and merges GitHub pull requests. It can be used via CLI on any PR, or configured with GitHub workflows to automatically monitor and fix bot PRs (Dependabot, pre-commit-ci) across an organization.

Prerequisites¶

Admin access to VectorInstitute organization
Anthropic API key
GitHub Personal Access Token with org-wide permissions

Setup Steps¶

1. Create Anthropic API Key¶

Go to Anthropic Console
Click "Create API Key"
Copy the key (starts with sk-ant-...)
Keep it secure - you'll add it as a secret

2. Create GitHub Personal Access Token¶

Option A: Fine-grained Token (Recommended)

Go to Fine-grained tokens
Click "Generate new token"
Configure:
Token name: aieng-bot-org-access
Expiration: 1 year
Resource owner: VectorInstitute
Repository access: All repositories
Permissions:
- contents: Read and write
- pull_requests: Read and write
- issues: Read and write
- metadata: Read-only (automatic)
Click "Generate token"
Copy the token (starts with github_pat_...)

Option B: Classic Token

Go to Personal access tokens (classic)
Configure:
Scopes: repo, workflow, read:org
Generate and copy token

3. Add Secrets to This Repository¶

Go to VectorInstitute/aieng-bot → Settings → Secrets and variables → Actions
Add two secrets:
ANTHROPIC_API_KEY: Your Anthropic API key
ORG_ACCESS_TOKEN: Your GitHub PAT

4. Enable GitHub Actions¶

Go to Actions tab
Enable workflows if disabled
Verify workflows appear:
discover-and-dispatch.yml
fix-pr-agent.yml

5. Test the Setup¶

Via CLI (recommended):

# Fix a PR directly
aieng-bot fix --repo owner/repo --pr 123

# Fix with dashboard logging
aieng-bot fix --repo owner/repo --pr 123 --log

Via GitHub Workflow:

# Trigger fix workflow for a specific PR
gh workflow run fix-pr-agent.yml \
  --field target_repo="owner/repo" \
  --field pr_number="123"

# Run bot PR discovery (VectorInstitute org)
gh workflow run discover-and-dispatch.yml

Via GitHub UI: Actions → Select workflow → Run workflow

6. Verify Bot Operation¶

After setup, the bot should: - Run daily at 00:00 UTC - Scan all VectorInstitute repositories - Find open bot PRs (Dependabot and pre-commit-ci) - Classify failures using Claude Haiku 4.5 - Auto-merge PRs with passing checks - Fix failing PRs using Claude Sonnet 4.5

Configuration¶

Adjust Monitoring Frequency¶

Edit .github/workflows/discover-and-dispatch.yml:

on:
  schedule:
    - cron: '0 0 * * *'    # Daily at midnight (default)
    # - cron: '0 */6 * * *'  # Every 6 hours
    # - cron: '0 */12 * * *' # Every 12 hours

Change Claude Model¶

Set CLAUDE_MODEL environment variable to override defaults: - Classification: claude-haiku-4-5-20251001 - Fixing: claude-sonnet-4-5-20250929

Customize Fix Skills¶

Edit skill definitions in .claude/skills/: - fix-merge-conflicts.md - fix-test-failures.md - fix-lint-failures.md - fix-security-audit.md - fix-build-failures.md

Security Considerations¶

Token Permissions¶

Use fine-grained token when possible
Set token expiration and rotate annually
Monitor usage in GitHub audit log
Never commit tokens to repository

API Key Protection¶

Monitor API usage in Anthropic Console
Rotate key periodically

Troubleshooting¶

Bot Not Finding PRs¶

# Test token access
gh api orgs/VectorInstitute/repos -H "Authorization: token $ORG_ACCESS_TOKEN"

Bot Can't Merge PRs¶

Ensure auto-merge enabled in target repo
Check branch protection rules
Verify token has contents: write

Claude API Errors¶

Verify API key at Anthropic Console
Check quota and rate limits

Workflow Not Running¶

Verify Actions enabled
Check secrets are set
Cron uses UTC timezone

Maintenance¶

Weekly¶

Review workflow runs for errors
Check PR comments for bot activity

Monthly¶

Review merged PRs for quality
Update skill templates based on patterns
Check for model updates

🤖 aieng-bot - AI-powered PR maintenance by Vector Institute AI Engineering