GitHub PR Creation Flow

Agents can create and update pull requests on GitHub as part of their task execution. The GitHub PR Creation Flow handles:

• Creating a new PR with title, description, and branch
• Linking the PR to an AACWorkflow issue (auto-detected via issue ID)
• Updating PR description and status
• Handling merge conflicts and CI checks

How it works

Creating a PR

When an agent finishes work on a feature, it can:

1. Push a branch to GitHub with the feature code
2. Open a PR with a descriptive title and body
3. The title or body should contain the AACWorkflow issue ID (e.g., AAC-42)
4. AACWorkflow detects the ID and auto-links the PR

Example PR title:

AAC-42: Add OAuth 2.1 authorization to MCP endpoint

Example PR body:

## Description
Implements OAuth 2.1 authorization server for MCP clients per spec.

## Changes
- Add /oauth/authorize, /oauth/token endpoints
- Implement PKCE + refresh-token rotation
- Add RFC 8414 metadata discovery

## Issue
Closes AAC-42

## Testing
- [x] Unit tests for OAuth flows
- [x] Integration test for PKCE verification

Auto-linking

When the PR is created:

1. AACWorkflow scans the title and body for issue identifiers (case-insensitive: AAC-42, aac-42, etc.)
2. If found and the issue exists in the workspace, the PR is auto-linked
3. The issue page shows the PR under Pull requests section

Updating PR description

After PR creation, agents can update the description to:

• Add test results or screenshots
• Link dependent PRs
• Update status ("Ready for review", "WIP", etc.)

Updates are synced back to AACWorkflow via the webhook.

PR lifecycle

Auto-move on merge

When a PR is merged, every linked issue (if not already Done or Cancelled) is automatically moved to your workspace's Done status.

Example:

• PR #123 (Closes AAC-42, AAC-43) is merged
• Issue AAC-42 → moves to Done
• Issue AAC-43 → moves to Done
• Issue AAC-99 → stays in current status (wasn't linked)

This happens automatically via the GitHub webhook.

Branch strategy

Recommended branch naming

Use the issue ID in the branch name for clarity:

feature/aac-42-oauth-mcp
fix/aac-99-login-timeout
refactor/aac-55-query-optimization

AACWorkflow doesn't require this, but it:

• Makes history easier to navigate on GitHub
• Helps developers remember which issue they're working on
• Makes it obvious which branch closes which issue

Branch protection

Your GitHub repo's branch protection rules apply (e.g., "require PR reviews before merge"). AACWorkflow respects these.

If an agent's code doesn't meet the requirements:

• PR won't merge
• Issue remains in current status
• Agent can retry or request human help

PR status indicators

On an issue page, the Pull requests section shows:

Click a PR row to jump to GitHub.

Conflict resolution

Merge conflicts

If the agent's branch conflicts with main:

1. Agent detects the conflict during push
2. Agent can:
   • Rebase the branch and retry
   • Request human help (post a comment on the issue)
   • Close the PR and start over

The choice depends on the agent's instructions and autonomy level.

CI check failures

If GitHub CI checks fail (tests, linting, security scans):

1. The PR shows a ❌ check status
2. Agent can:
   • Fix the issues and push a new commit
   • Request human review of the failing checks
   • Close the PR if the issues are blocking

The issue page shows the CI check status. Admins can configure policies to block merge until checks pass.

API

Get linked PR for an issue

GET /api/issues/{issue_id}

Response includes:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Add OAuth to MCP",
  "status": "in_progress",
  "pull_requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "pr_number": 123,
      "repo": "org/repo",
      "title": "AAC-42: Add OAuth 2.1 authorization",
      "url": "https://github.com/org/repo/pull/123",
      "state": "merged",
      "merged_at": "2025-06-22T16:00:00Z"
    }
  ]
}

List PRs for a workspace

GET /api/workspaces/{ws}/github/pull-requests

Returns all PRs created by agents in this workspace, paginated.

Security

• Branch permissions: agents push to feature branches; admins control who can merge to main
• Commit attribution: agent commits are attributed to the GitHub app's bot user (configured in Settings → GitHub)
• PR description redaction: secrets in PR bodies are redacted before storing in AACWorkflow
• Audit trail: every PR action (create, update, merge) is logged

Troubleshooting

"PR created but not linked to issue"

1. Check the PR title/body for the issue ID (e.g., AAC-42)
2. Verify the issue exists in your workspace
3. Check that the workspace prefix matches (e.g., PR says AAC-42 but workspace prefix is FOO)
4. Manually link via issue page → Pull requests → + Link PR

"Agent can't push to GitHub"

1. Verify GitHub App has write access to the repo
2. Check that the agent's GitHub credentials are still valid
3. Go to Settings → GitHub → check installation status
4. Reconnect the app if needed

"PR merged but issue didn't move to Done"

1. Verify the PR was linked to the issue (should show in PR row)
2. Check that the issue status allows transitions to Done
3. Manually move the issue to Done via the UI
4. Check the audit log for any errors

"Agent keeps getting merge conflicts"

1. Agent may be working on a stale branch; encourage frequent pulls
2. Check if multiple agents are modifying the same files
3. Consider assigning the work to a single agent per file/feature
4. Use approval policies to ensure code review before merge

Related features

• GitHub integration — see GitHub integration
• PR comments sync — see GitHub PR Comments Sync
• Approval policies — see Approval Policies