GitHub Integration¶

GitHub integration enables version control, PR management, and issue tracking via the GitHub MCP server.

Configuration¶

Primary Repository: aegis-agent/aegis-core SSH Key: ~/.ssh/id_ed25519_github (used for both GitHub and Dockerhost)

Configuration in ~/.claude.json:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/github/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "<github-token>"
      }
    }
  }
}

MCP Tools¶

Repository Operations¶

# Search repositories
repos = mcp__github__search_repositories(
    query="aegis language:python"
)

# Get repository info
repo = mcp__github__get_repository(
    owner="aegis-agent",
    repo="aegis-core"
)

# List branches
branches = mcp__github__list_branches(
    owner="aegis-agent",
    repo="aegis-core"
)

Pull Requests¶

# List PRs
prs = mcp__github__list_pull_requests(
    owner="aegis-agent",
    repo="aegis-core",
    state="open"
)

# Get PR details
pr = mcp__github__get_pull_request(
    owner="aegis-agent",
    repo="aegis-core",
    pr_number=42
)

# Create PR
pr = mcp__github__create_pull_request(
    owner="aegis-agent",
    repo="aegis-core",
    title="Add new feature",
    body="Description of changes",
    head="feature-branch",
    base="main"
)

# Review PR
mcp__github__create_review(
    owner="aegis-agent",
    repo="aegis-core",
    pr_number=42,
    event="APPROVE",  # or "REQUEST_CHANGES", "COMMENT"
    body="LGTM! Approved."
)

Issues¶

# List issues
issues = mcp__github__list_issues(
    owner="aegis-agent",
    repo="aegis-core",
    state="open"
)

# Create issue
issue = mcp__github__create_issue(
    owner="aegis-agent",
    repo="aegis-core",
    title="Bug: Authentication fails",
    body="Description of the bug...",
    labels=["bug", "high-priority"]
)

# Add comment
mcp__github__create_issue_comment(
    owner="aegis-agent",
    repo="aegis-core",
    issue_number=123,
    body="Working on this now."
)

File Operations¶

# Get file contents
content = mcp__github__get_file_contents(
    owner="aegis-agent",
    repo="aegis-core",
    path="README.md",
    ref="main"
)

# Create/update file
mcp__github__create_or_update_file(
    owner="aegis-agent",
    repo="aegis-core",
    path="docs/new-doc.md",
    message="Add new documentation",
    content="Base64-encoded content",
    branch="main"
)

Git Workflow¶

Commit with Co-Author Attribution¶

All commits include Claude Code attribution:

git commit -m "$(cat <<'EOF'
feat: Add new feature

Implemented feature X with Y approach.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

Using Git from Code¶

# Always use -C flag or cd to specify directory
git -C /home/agent/projects/aegis-core status
git -C /home/agent/projects/aegis-core add .
git -C /home/agent/projects/aegis-core commit -m "Update docs"
git -C /home/agent/projects/aegis-core push

PR Creation Workflow¶

When creating a pull request:

Check current branch status:

git -C /home/agent/projects/aegis-core status
git -C /home/agent/projects/aegis-core diff main...HEAD
git -C /home/agent/projects/aegis-core log main..HEAD

Draft PR summary (analyze ALL commits, not just latest):

## Summary
- Feature A implemented
- Bug B fixed
- Documentation updated

## Test plan
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing complete

Create PR using gh:

gh pr create --title "Title" --body "$(cat <<'EOF'
## Summary
...

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Repository Structure¶

aegis-agent/aegis-core/
├── aegis/               # Main package
│   ├── whatsapp/       # WhatsApp integration
│   ├── discord/        # Discord integration
│   ├── monetization/   # Revenue systems
│   ├── revenue/        # Revenue engine
│   └── ...
├── docs/               # Documentation
├── tests/              # Test suite
├── scripts/            # Utility scripts
└── README.md          # Project overview

SSH Configuration¶

SSH config (~/.ssh/config):

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes

Best Practices¶

Commit Messages¶

Follow conventional commits format:

<type>(<scope>): <subject>

<body>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Types: feat, fix, docs, refactor, test, chore

Branch Naming¶

feature/<description>     # New features
fix/<description>         # Bug fixes
docs/<description>        # Documentation
refactor/<description>    # Code refactoring

PR Guidelines¶

Title: Clear, concise description
Summary: Bullet points of changes
Test Plan: Checklist of testing steps
Links: Reference related issues
Attribution: Include Claude Code footer

Security¶

Never commit secrets: Use .gitignore for .env, .secure/, credentials
Review diffs: Always check git diff before committing
Signed commits: Use GPG signing for verified commits (optional)

Automation¶

PR Review Skill¶

The /pr-review skill automates code reviews:

# Review a PR
/pr-review 42

# Or via MCP
mcp__github__get_pull_request(owner="aegis-agent", repo="aegis-core", pr_number=42)

Checks: - Code quality (linting, formatting) - Test coverage - Security issues - Best practices - Documentation

CI/CD Integration¶

GitHub Actions can trigger on: - Push to main - PR creation/update - Issue creation - Release creation

Troubleshooting¶

Authentication Failures¶

Regenerate GitHub token: 1. Go to https://github.com/settings/tokens 2. Generate new token with repo scope 3. Update ~/.claude.json

Push Rejected¶

# Pull latest changes
git -C /home/agent/projects/aegis-core pull --rebase

# Resolve conflicts if any
git -C /home/agent/projects/aegis-core rebase --continue

# Push
git -C /home/agent/projects/aegis-core push

MCP Server Not Working¶

Check MCP server logs:

# View Claude logs
tail -f ~/.claude/logs/main.log

# Test GitHub API directly
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/aegis-agent/aegis-core

Advanced Features¶

GitHub CLI (`gh`)¶

# View PR
gh pr view 42

# List PRs
gh pr list --state open

# Check PR checks
gh pr checks 42

# Merge PR
gh pr merge 42 --squash

Webhooks¶

Configure webhooks to trigger Aegis workflows:

{
  "url": "https://aegisagent.ai/api/github/webhook",
  "content_type": "json",
  "secret": "<webhook-secret>",
  "events": ["push", "pull_request", "issues"]
}

Repository Insights¶

# Get commit activity
activity = mcp__github__get_commit_activity(
    owner="aegis-agent",
    repo="aegis-core"
)

# Get contributors
contributors = mcp__github__list_contributors(
    owner="aegis-agent",
    repo="aegis-core"
)