GitHub SCM Plugin

The GitHub SCM plugin provides comprehensive GitHub integration for pull request management, CI/CD monitoring, code review tracking, and merge readiness checks.

Overview

This plugin uses the GitHub CLI (gh) to interact with the GitHub API. It monitors PR state, CI checks, code reviews, and determines when PRs are ready to merge. The orchestrator uses this information to automatically handle routine tasks and notify humans only when their judgment is needed.

The SCM plugin is designed for push-based workflows: agents create PRs, the orchestrator monitors CI/reviews, and auto-merges when ready.

Configuration

Configure the GitHub SCM plugin in your agent-orchestrator.yaml:

plugins:
  scm:
    name: github

projects:
  - id: my-app
    repo: owner/repo-name  # GitHub repository in owner/repo format

Configuration Options

The GitHub SCM plugin requires no additional configuration parameters. All settings are derived from the project’s repo field.

repo

string

required

GitHub repository in owner/repo format (e.g., octocat/hello-world).

Requirements

Prerequisites:

GitHub CLI (gh) installed and in PATH
Authenticated with gh auth login
Read/write access to pull requests in the target repository
Repository must have Actions or Checks configured for CI

Installing GitHub CLI

# macOS
brew install gh

# Linux (Debian/Ubuntu)
sudo apt install gh

# Login
gh auth login

Verifying Authentication

# Check authentication status
gh auth status

# Test PR access
gh pr list --repo owner/repo-name --limit 5

Features

PR Detection and State

Detect PR Find a PR for a specific branch:

const pr = await scm.detectPR(session, project);
// Returns: PRInfo | null
// { number, url, title, owner, repo, branch, baseBranch, isDraft }

Get PR State Check if a PR is open, closed, or merged:

const state = await scm.getPRState(pr);
// Returns: "open" | "closed" | "merged"

Get PR Summary Get high-level PR information:

const summary = await scm.getPRSummary(pr);
// Returns: { state, title, additions, deletions }

PR Lifecycle

Merge PR Merge a PR with configurable merge method:

await scm.mergePR(pr, "squash");  // "squash" | "merge" | "rebase"
// Automatically deletes the branch after merge

Close PR Close a PR without merging:

await scm.closePR(pr);

CI/CD Monitoring

Get CI Checks Fetch all CI checks for a PR:

const checks = await scm.getCIChecks(pr);
// Returns: CICheck[]
// [
//   { name: "Build", status: "passed", url: "...", conclusion: "SUCCESS", ... },
//   { name: "Test", status: "running", ... },
//   { name: "Lint", status: "failed", ... }
// ]

Get CI Summary Get high-level CI status:

const status = await scm.getCISummary(pr);
// Returns: "passing" | "failing" | "pending" | "none"

CI Summary Logic:

passing: All checks passed (at least one check exists)
failing: At least one check failed
pending: No failures, but at least one check is pending/running
none: No checks configured or PR is merged/closed

CI Check Status Mapping

GitHub Check State → CI Status:

GitHub State	CI Status
`SUCCESS`	`passed`
`PENDING`, `QUEUED`	`pending`
`IN_PROGRESS`	`running`
`FAILURE`, `TIMED_OUT`, `CANCELLED`	`failed`
`SKIPPED`, `NEUTRAL`	`skipped`
Unknown	`failed` (fail-closed)

Code Review Tracking

Get Reviews Fetch all reviews for a PR:

const reviews = await scm.getReviews(pr);
// Returns: Review[]
// [
//   { author: "reviewer1", state: "approved", body: "LGTM", submittedAt: Date },
//   { author: "reviewer2", state: "changes_requested", body: "...", submittedAt: Date }
// ]

Get Review Decision Get the overall review decision (GitHub’s aggregate status):

const decision = await scm.getReviewDecision(pr);
// Returns: "approved" | "changes_requested" | "pending" | "none"

Review Comments

Get Pending Comments Fetch unresolved review comments (excludes bot comments):

const comments = await scm.getPendingComments(pr);
// Returns: ReviewComment[]
// [
//   {
//     id: "comment-123",
//     author: "reviewer1",
//     body: "This could be refactored...",
//     path: "src/index.ts",
//     line: 42,
//     isResolved: false,
//     createdAt: Date,
//     url: "..."
//   }
// ]

Pending comments only include unresolved threads from human reviewers. Bot comments are filtered out.

Get Automated Comments Fetch comments from bots (CI tools, linters, security scanners):

const botComments = await scm.getAutomatedComments(pr);
// Returns: AutomatedComment[]
// [
//   {
//     id: "comment-456",
//     botName: "codecov[bot]",
//     body: "Coverage decreased by 2%",
//     path: "src/utils.ts",
//     line: 15,
//     severity: "warning",  // "error" | "warning" | "info"
//     createdAt: Date,
//     url: "..."
//   }
// ]

Known Bot Authors

The plugin filters these bot accounts:

cursor[bot]
github-actions[bot]
codecov[bot]
sonarcloud[bot]
dependabot[bot]
renovate[bot]
codeclimate[bot]
deepsource-autofix[bot]
snyk-bot
lgtm-com[bot]

Merge Readiness

Get Mergeability Comprehensive merge readiness check:

const readiness = await scm.getMergeability(pr);
// Returns: MergeReadiness
// {
//   mergeable: true,        // Overall readiness
//   ciPassing: true,        // All CI checks passed
//   approved: true,         // Reviews approved
//   noConflicts: true,      // No merge conflicts
//   blockers: []            // List of blocking issues
// }

Blocker Examples When mergeable: false, the blockers array contains reasons:

blockers: [
  "CI is failing",
  "Changes requested in review",
  "Merge conflicts",
  "Branch is behind base branch",
  "PR is still a draft",
  "Review required",
  "Merge is blocked by branch protection",
  "Required checks are failing"
]

The plugin uses a fail-closed approach: if it can’t determine CI status or review state, it reports the PR as not ready to merge.

Usage Example

Auto-Merge Workflow

# agent-orchestrator.yaml
reactions:
  - event: ci_passed
    conditions:
      - type: review_approved
      - type: no_conflicts
    action: merge_pr
    merge_method: squash

This configuration automatically merges PRs when:

All CI checks pass
Reviews are approved
No merge conflicts exist

Monitor PR Progress

# Check PR status
ao status session-id

# Output:
# PR #123: Fix login bug
# State: open
# CI: passing (3/3 checks)
# Reviews: approved
# Blockers: Branch is behind base branch

Handle CI Failures

reactions:
  - event: ci_failed
    action: notify
    message: "CI failed on PR {{pr.number}}: {{pr.url}}"

Troubleshooting

Error: gh command not found

The GitHub CLI is not installed or not in PATH.Solution:

# macOS
brew install gh

# Linux
sudo apt install gh

# Verify
which gh

Error: Failed to fetch CI checks

The plugin couldn’t retrieve CI check status.Common causes:

No CI checks configured for the repository
GitHub API timeout
Network connectivity issues
PR is closed/merged (no check data)

The plugin fails closed: reports CI as “failing” to prevent auto-merge.

CI status shows 'none' but checks exist

This happens when all checks are skipped or neutral.The plugin only reports passing if at least one check actually passed (not all skipped).

Review decision is 'none' but reviews exist

GitHub’s reviewDecision field aggregates reviews. It’s none when:

No review is required by branch protection
All reviews are comments (not approvals or change requests)
Reviews were dismissed

Pending comments include bot comments

The plugin filters bot comments using a predefined list of known bot authors.If a new bot is not filtered, add it to BOT_AUTHORS in the source code:

const BOT_AUTHORS = new Set([
  "cursor[bot]",
  "your-new-bot[bot]",  // Add here
  // ...
]);

Merge fails with 'blocked by branch protection'

GitHub branch protection rules are preventing the merge.Common protections:

Required reviews not met
Required status checks not passed
Branch not up to date with base
Signed commits required

Check repository settings → Branches → Branch protection rules.

PR state is 'unknown' in mergeability check

GitHub is still computing merge state (happens for large PRs or complex conflicts).The plugin reports this as a blocker: “Merge status unknown (GitHub is computing)”Wait a few seconds and check again.

API Reference

SCM Interface Methods

detectPR(session, project)

Finds PR by branch name
Returns: PRInfo | null

getPRState(pr)

Returns: "open" | "closed" | "merged"

getPRSummary(pr)

Returns: { state, title, additions, deletions }

mergePR(pr, method)

Merges PR with specified method
Deletes branch automatically
Returns: void

closePR(pr)

Closes PR without merging
Returns: void

getCIChecks(pr)

Returns: CICheck[]

getCISummary(pr)

Returns: "passing" | "failing" | "pending" | "none"

getReviews(pr)

Returns: Review[]

getReviewDecision(pr)

Returns: "approved" | "changes_requested" | "pending" | "none"

getPendingComments(pr)

Returns: ReviewComment[] (human reviewers only)

getAutomatedComments(pr)

Returns: AutomatedComment[] (bots only)

getMergeability(pr)

Returns: MergeReadiness

Advanced Usage

Merge Methods

// Squash: All commits into one (default)
await scm.mergePR(pr, "squash");

// Merge: Create merge commit
await scm.mergePR(pr, "merge");

// Rebase: Rebase and fast-forward
await scm.mergePR(pr, "rebase");

CI Monitoring Loop

// Poll CI status until completion
let status = await scm.getCISummary(pr);
while (status === "pending") {
  await sleep(30_000);  // Wait 30 seconds
  status = await scm.getCISummary(pr);
}

if (status === "passing") {
  console.log("CI passed!");
} else if (status === "failing") {
  const checks = await scm.getCIChecks(pr);
  const failed = checks.filter(c => c.status === "failed");
  console.error(`CI failed: ${failed.map(c => c.name).join(", ")}`);
}

Review Comment Handling

// Check for pending human review comments
const pending = await scm.getPendingComments(pr);
if (pending.length > 0) {
  console.log(`${pending.length} unresolved comments`);
  for (const comment of pending) {
    console.log(`${comment.path}:${comment.line} - ${comment.author}`);
    console.log(comment.body);
  }
}

// Check for automated feedback
const automated = await scm.getAutomatedComments(pr);
const errors = automated.filter(c => c.severity === "error");
if (errors.length > 0) {
  console.log(`${errors.length} automated errors to address`);
}

Comprehensive Merge Check

const readiness = await scm.getMergeability(pr);

if (readiness.mergeable) {
  await scm.mergePR(pr, "squash");
  console.log("PR merged successfully!");
} else {
  console.log("PR not ready to merge:");
  for (const blocker of readiness.blockers) {
    console.log(`  - ${blocker}`);
  }
}

Integration with Other Plugins

With Tracker Plugin

The SCM and tracker plugins work together:

Tracker creates issue and generates prompt
Agent writes code and creates PR
SCM monitors CI and reviews
Tracker updates issue when PR merges

reactions:
  - event: pr_created
    action: run
    command: |
      # Link PR to Linear issue
      echo "PR created: $PR_URL" >> $ISSUE_COMMENT
  
  - event: pr_merged
    action: run
    command: |
      # Close issue
      ao tracker update $ISSUE_ID --state closed --comment "Fixed in PR $PR_URL"

With Notifier Plugin

Send notifications based on PR events:

reactions:
  - event: ci_failed
    action: notify
    channel: slack
    message: |
      CI failed on PR #{{pr.number}}
      {{pr.url}}
      
      Failed checks:
      {{#each failedChecks}}
      - {{name}}: {{url}}
      {{/each}}
  
  - event: changes_requested
    action: notify
    channel: desktop
    message: "Changes requested on PR #{{pr.number}}"

Performance Considerations

API Calls

The plugin makes multiple API calls per operation:

getMergeability: 3-4 calls (PR state, CI, reviews, merge status)
getCIChecks: 1 call
getReviews: 1 call
getPendingComments: 1 call (GraphQL)

Rate Limits

GitHub API rate limits (authenticated):

REST API: 5,000 requests/hour
GraphQL API: 5,000 points/hour

The gh CLI handles authentication and rate limiting automatically.

Caching

The plugin does not cache responses. The orchestrator should implement caching if polling frequently.

Security Considerations

All GitHub API calls are made through the gh CLI (no direct token handling)
Commands are executed with execFile (not exec) to prevent shell injection
30-second timeout prevents hanging on network issues
Repository format is validated before use
Fail-closed approach: unknown states are treated as blocking

Source Code

Source: packages/plugins/scm-github/src/index.ts

Overview

Runtime Plugins

Agent Plugins

Workspace Plugins

Tracker Plugins

SCM Plugins

Notifier Plugins

Terminal Plugins

​GitHub SCM Plugin

​Overview

​Configuration

​Configuration Options

​Requirements

​Installing GitHub CLI

​Verifying Authentication

​Features

​PR Detection and State

​PR Lifecycle

​CI/CD Monitoring

​CI Check Status Mapping

​Code Review Tracking

​Review Comments

​Known Bot Authors

​Merge Readiness

​Usage Example

​Auto-Merge Workflow

​Monitor PR Progress

​Handle CI Failures

​Troubleshooting

​API Reference

​SCM Interface Methods

​Advanced Usage

​Merge Methods

​CI Monitoring Loop

​Review Comment Handling

​Comprehensive Merge Check

​Integration with Other Plugins

​With Tracker Plugin

​With Notifier Plugin

​Performance Considerations

​API Calls

​Rate Limits

​Caching

​Security Considerations

​Source Code

Build docs developers (and LLMs) love

GitHub SCM Plugin

Overview

Configuration

Configuration Options

Requirements

Installing GitHub CLI

Verifying Authentication

Features

PR Detection and State

PR Lifecycle

CI/CD Monitoring

CI Check Status Mapping

Code Review Tracking

Review Comments

Known Bot Authors

Merge Readiness

Usage Example

Auto-Merge Workflow

Monitor PR Progress

Handle CI Failures

Troubleshooting

API Reference

SCM Interface Methods

Advanced Usage

Merge Methods

CI Monitoring Loop

Review Comment Handling

Comprehensive Merge Check

Integration with Other Plugins

With Tracker Plugin

With Notifier Plugin

Performance Considerations

API Calls

Rate Limits

Caching

Security Considerations

Source Code