GitHub PR Comments Sync

The GitHub PR Comments Sync feature keeps comments in sync between GitHub pull requests and AACWorkflow, so team discussions stay unified and up-to-date on both sides.

How it works

Sync directions

GitHub → AACWorkflow: When someone posts a comment on a GitHub PR, AACWorkflow mirrors it to the linked issue (if there is one). The comment is attributed to the GitHub user and marked with a GitHub badge.

AACWorkflow → GitHub: When someone comments on an AACWorkflow issue that has a linked GitHub PR, AACWorkflow posts the comment to the PR thread (if configured).

Example flow

1. You create a PR: #123 Add OAuth support
2. PR title matches an AACWorkflow issue: AAC-42
3. The issue page shows: Pull requests → #123 Add OAuth support
4. A reviewer posts a comment on the PR: "Good approach, but let's add type safety to the token handler"
5. AACWorkflow automatically mirrors the comment to the issue thread
6. Team members see the same feedback in both places

Comment metadata

Synced comments carry metadata so you know their origin:

When viewing comments, you'll see:

• Original author — GitHub username or AACWorkflow user
• Original timestamp — when the comment was first posted
• Link to original — click to jump to the source (GitHub PR or AACWorkflow thread)

Controlling sync behavior

Per-issue sync setting

Go to an issue with a linked PR. In the Pull requests section, click the PR row to open the PR panel. Toggle:

Sync comments → ON/OFF

When on, new comments on the PR are mirrored to AACWorkflow. Existing comments are not retroactively synced.

When off, the link remains (for reference) but no new comments are mirrored.

Workspace-wide sync policy

Go to Settings → GitHub → Comment Sync Policy to set defaults:

Individual issues can override the workspace policy.

Comment deduplication

If a comment is posted simultaneously on both GitHub and AACWorkflow (rare), AACWorkflow uses an idempotency key to avoid duplicates. The system checks:

• Author + timestamp + first 100 chars of content = unique identity
• Duplicate posts within 10 seconds → deduplicated

Redaction & privacy

Sensitive information in comments is not automatically redacted. If a comment contains secrets (API keys, tokens, credentials):

1. Delete it immediately from the source (GitHub or AACWorkflow)
2. The deletion is not synced — you must delete both copies manually
3. Consider using a pre-commit hook to catch secrets before they reach either platform

Threading & context

PR comments are synced as thread replies on the AACWorkflow issue:

• GitHub PR: review comments on a specific line/file
• AACWorkflow: inline comments are collected into a PR Comments section of the issue timeline

Replies within a GitHub PR thread are synced as nested replies in AACWorkflow.

Limitations

• Not synced: PR review events (approve/request changes), commit comments, file-specific review comments map to the PR-level thread only
• One-way for certain events: GitHub PR "ready for review" status does not map to AACWorkflow status changes
• Comment edits: edits on GitHub are synced (updated timestamp shown); edits on AACWorkflow are not synced back to GitHub (GitHub API limitation)
• Comment deletions: deletions on either side are not synced; you must delete both copies manually

API

Sync comments for a PR

POST /api/issues/{issue_id}/github/pr/{pr_number}/sync-comments

Manually trigger a comment sync for this PR. Returns:

{
  "synced_count": 5,
  "new_comments": 3,
  "updated_comments": 2,
  "skipped": 0
}

List synced comments for an issue

GET /api/issues/{issue_id}/github/pr-comments

Returns:

{
  "comments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "pr_number": 123,
      "github_comment_id": "1234567890",
      "author": "jane-smith",
      "author_type": "github",
      "body": "Good approach, but let's add type safety...",
      "created_at": "2025-06-22T15:30:00Z",
      "synced_at": "2025-06-22T15:30:05Z",
      "url": "https://github.com/org/repo/pull/123#discussion_r1234567890"
    }
  ]
}

Disable sync for an issue

PATCH /api/issues/{issue_id}/github/sync

Body:

{
  "sync_pr_comments": false
}

Troubleshooting

"Comments from GitHub aren't showing up"

1. Check that Sync comments is enabled in the PR panel
2. Check the workspace sync policy (Settings → GitHub)
3. Wait 30 seconds — sync runs on a background worker
4. If still missing, click Sync now to force a refresh

"Comment appears on GitHub but not AACWorkflow"

1. Verify the GitHub PR is linked to the AACWorkflow issue
2. Check the issue page → Pull requests section
3. If the PR isn't listed, re-run GitHub issue/PR import (Settings → GitHub)

"I posted a comment in AACWorkflow but it's not on GitHub"

1. Verify Sync comments is enabled for this PR
2. Check that you have write access to the GitHub repo
3. Look at the issue's audit log (Settings → Audit) for sync errors

"Same comment appearing multiple times"

This can happen if sync was triggered manually (/sync-comments) while the background worker was also running. Click Delete on the duplicate and it will be removed from both sides (one-click cleanup).

Best practices

1. Use GitHub for code review — detailed line-by-line feedback
2. Use AACWorkflow for task context — why the PR was created, what it depends on
3. Link PRs early — mention the issue ID in the branch name or PR title so the link is auto-detected
4. Don't cross-post manually — don't paste the same comment in both places; let sync handle it
5. Review settings before big PRs — set your sync policy before large team PRs to avoid duplicates

Related features

• GitHub issue import — see GitHub Issue Import & Export
• GitHub PR integration — see GitHub integration