GitHub is where your code lives, and it is where your AI agents do their best work. This guide covers everything you need to know about connecting agent.ceo to your GitHub repositories, configuring permissions, and enabling agents to review PRs, submit fixes, and monitor CI pipelines.

By the end of this tutorial, your agents will be fully integrated with GitHub and ready to participate in your development workflow as autonomous team members.

What Agents Can Do with GitHub

Once connected, agents can:

Review pull requests: Analyze code changes, suggest improvements, approve or request changes
Submit fixes: Create branches, commit code changes, and open PRs
Monitor CI: Watch pipeline status, diagnose failures, and suggest fixes
Manage issues: Triage bugs, create sub-tasks, update labels
Audit dependencies: Track outdated packages and security vulnerabilities
Enforce standards: Check code against your style guides and architecture decisions

This is possible because each agent gets a full development environment with git access, as described in our Kubernetes deployment guide.

Prerequisites

An agent.ceo account (see Getting Started)
Admin or owner access to the GitHub organization you want to connect
At least one active repository

Step 1: Install the agent.ceo GitHub App

Navigate to Settings > Integrations > GitHub in your agent.ceo dashboard and click Connect GitHub.

This redirects you to GitHub to install the agent.ceo GitHub App:

https://github.com/apps/agent-ceo/installations/new

[Screenshot: GitHub App installation page showing organization selection and repository access options]

Choose your installation scope:

All repositories: Agents can access every repo in the organization
Select repositories: Choose specific repos for agent access

For initial setup, we recommend selecting specific repositories and expanding access as you gain confidence.

Step 2: Configure Repository Permissions

The GitHub App requests the following permissions:

permissions:
  # Required permissions
  contents: read        # Clone and read repository files
  pull_requests: write  # Create, review, and comment on PRs
  issues: write         # Create and manage issues
  metadata: read        # Basic repository metadata
  
  # Recommended permissions
  checks: write         # Create check runs for agent analysis
  actions: read         # Monitor CI/CD workflow status
  workflows: write      # Trigger workflow runs
  
  # Optional permissions
  administration: read  # Read branch protection rules
  statuses: write       # Update commit statuses
  packages: read        # Access GitHub Packages

You can accept all permissions or limit them based on your security requirements. Agents will gracefully degrade functionality when permissions are restricted.

Step 3: Configure Webhook Events

agent.ceo automatically configures webhooks for the events your agents need:

webhook_events:
  # Pull request events
  - pull_request.opened
  - pull_request.synchronize
  - pull_request.closed
  - pull_request.review_requested
  
  # Push events
  - push
  
  # Issue events
  - issues.opened
  - issues.assigned
  - issues.labeled
  
  # CI/CD events
  - check_run.completed
  - workflow_run.completed
  - status
  
  # Review events
  - pull_request_review.submitted
  - pull_request_review_comment.created

[Screenshot: Webhook configuration showing event subscriptions with checkmarks]

These events trigger agent actions. For example, when a pull_request.opened event fires, the code review agent activates and begins analyzing the changes.

Step 4: Map Repositories to Agents

Define which agents watch which repositories:

# Assign repos to specific agents
agentceo agent assign CodeReviewer \
  --repos org/api-service,org/web-frontend,org/mobile-app

# Assign all repos to security agent
agentceo agent assign SecurityAnalyst \
  --repos org/*

# Assign infrastructure repos to DevOps agent
agentceo agent assign DevOpsEngineer \
  --repos org/infrastructure,org/helm-charts,org/terraform

Or configure through the dashboard:

[Screenshot: Repository assignment panel showing a matrix of agents and repositories with checkboxes]

Step 5: Set Up Agent Git Identity

Each agent gets a dedicated Git identity for commits and PRs:

# Agent Git configuration (auto-generated)
git config user.name "agent-ceo[bot]"
git config user.email "agent-ceo[bot]@users.noreply.github.com"

When agents create branches or submit PRs, they appear with the bot identity, making it clear which changes are human-authored vs. agent-authored.

You can customize the identity per agent:

# Custom git identity for an agent
agent:
  name: "SecurityAnalyst"
  git_identity:
    name: "security-bot"
    email: "security-bot@yourcompany.com"
  branch_prefix: "security/"
  commit_prefix: "security: "

Step 6: Configure Branch Protection Compatibility

If your repositories use branch protection rules, configure agents to work within those constraints:

# Branch protection compatible configuration
github_workflow:
  branch_strategy:
    create_feature_branches: true
    branch_naming: "{agent-name}/{task-type}/{short-description}"
    base_branch: "main"
    require_pr: true
    auto_merge: false  # Require human approval for merges
  
  pr_workflow:
    draft_first: true       # Create as draft, mark ready when complete
    request_review: true    # Request review from code owners
    add_labels: true        # Label with agent-generated, task-type
    link_issues: true       # Auto-link related issues

# Example: Agent creates a branch and PR for a bug fix
# Agent workflow:
git checkout -b security-bot/fix/sql-injection-user-input
# Agent makes code changes...
git add src/api/users.ts
git commit -m "security: sanitize user input to prevent SQL injection"
git push origin security-bot/fix/sql-injection-user-input
gh pr create \
  --title "security: sanitize user input to prevent SQL injection" \
  --body "Fixes #142. Added parameterized queries to user input handlers." \
  --label "security,agent-generated" \
  --draft

Step 7: Enable CI Integration

Agents can monitor and respond to CI pipeline results:

# CI integration configuration
ci_integration:
  watch_workflows:
    - name: "tests"
      on_failure:
        - analyze-logs
        - suggest-fix
        - notify-slack
    - name: "lint"
      on_failure:
        - auto-fix
        - push-fix
    - name: "security-scan"
      on_failure:
        - create-issue
        - notify-security-channel
  
  auto_retry:
    enabled: true
    max_retries: 2
    retry_on:
      - "flaky-test"
      - "timeout"
      - "rate-limit"

When a CI run fails, the agent:

Pulls the failure logs
Analyzes the root cause
Either fixes the issue automatically or reports findings

# Example agent CI failure response:
# 1. Agent detects CI failure on PR #87
# 2. Downloads workflow logs
# 3. Identifies failing test: test_user_auth.py::test_token_expiry
# 4. Analyzes that a recent change modified token lifetime
# 5. Pushes a fix or comments with diagnosis

Step 8: Configure Repository Context

Help agents understand your codebase by providing context files:

# Create agent context in your repository
mkdir -p .agent-ceo/

# Define coding standards
cat > .agent-ceo/standards.md << 'EOF'
# Coding Standards

- Use TypeScript strict mode
- All functions must have JSDoc comments
- Maximum function length: 50 lines
- Prefer composition over inheritance
- All API endpoints must have input validation
EOF

# Define review checklist
cat > .agent-ceo/review-checklist.md << 'EOF'
# PR Review Checklist

- [ ] Tests cover new functionality
- [ ] No hardcoded secrets or credentials
- [ ] Error handling is comprehensive
- [ ] API changes are backward compatible
- [ ] Performance impact is acceptable
- [ ] Documentation is updated
EOF

Agents automatically read these files from your repository to inform their decisions, similar to how knowledge base ingestion works for broader context.

Step 9: Test the Integration

Verify everything works by triggering a complete workflow:

# Create a test branch with an intentional issue
git checkout -b test/github-integration
cat >> src/api/handler.ts << 'EOF'

// Intentional issue: SQL injection vulnerability
export function getUser(userId: string) {
  const query = `SELECT * FROM users WHERE id = '${userId}'`;
  return db.query(query);
}
EOF

git add src/api/handler.ts
git commit -m "test: verify agent GitHub integration"
git push origin test/github-integration
gh pr create \
  --title "test: verify agent GitHub integration" \
  --body "Testing that agents can review and comment on PRs"

Within 1-2 minutes, you should see:

CodeReviewer comments on code quality issues
SecurityAnalyst flags the SQL injection vulnerability
Both agents add appropriate labels to the PR

[Screenshot: GitHub PR showing bot comments from code review and security agents with specific line annotations]

Troubleshooting

Agent does not respond to PR events:

Verify the GitHub App is installed and has access to the repository
Check webhook delivery in GitHub (Settings > Webhooks > Recent Deliveries)
Ensure the agent is assigned to watch that repository

Agent cannot push branches:

Verify contents: write permission is granted
Check branch protection rules allow the bot to push
Ensure the agent's branch prefix is not restricted

CI monitoring not working:

Confirm actions: read and checks: write permissions
Verify workflow event subscriptions are active
Check that the agent role includes CI monitoring capabilities

Rate limiting issues:

GitHub has API rate limits (5000 requests/hour for authenticated apps)
Configure agent polling intervals to stay within limits
Use webhook events instead of polling where possible

Security Best Practices

Principle of least privilege: Only grant permissions agents actually need
Repository allowlists: Explicitly define which repos each agent can access
Branch restrictions: Limit which branches agents can push to
Audit logging: Review agent actions in the monitoring dashboard
Token rotation: agent.ceo handles OAuth token refresh automatically
Secrets scanning: Never store tokens in agent configurations -- use Kubernetes secrets

For comprehensive security setup, see our guide on automated security auditing.

Whether you choose the hosted SaaS platform or a private enterprise installation, agent.ceo delivers the same autonomous workforce capabilities.

Try agent.ceo

SaaS — Get started with 1 free agent-week at agent.ceo.

Enterprise — For private installation on your own infrastructure, contact enterprise@agent.ceo.

agent.ceo is built by GenBrain AI — a GenAI-first autonomous agent orchestration platform. General inquiries: hello@agent.ceo | Security: security@agent.ceo

Connecting AI Agents to Your GitHub Repos