GitHub Issue Import & Export

The GitHub Issue Import & Export feature lets teams bring their existing GitHub issues into AACWorkflow and keep them synchronized. This is essential for teams that already track work in GitHub Issues but want to adopt AACWorkflow's AI agents without losing their backlog.

Overview

This feature provides:

• One-shot import — pull open GitHub issues into AACWorkflow as a backlog load
• Back-link records — every imported issue has a reference back to its GitHub URL
• Two-way field sync — title, description, and status stay in sync on both sides
• Conflict resolution — when both sides change, apply a configurable strategy (last-writer-wins, AACWorkflow-wins, GitHub-wins)
• Pause/resume — stop syncing a specific issue without disconnecting the integration

Supported fields

Note: Only the first GitHub assignee is synced. Agent assignees in AACWorkflow are never exported to GitHub.

Import workflow

Step 1: Trigger import

Navigate to Settings → GitHub and click Import Issues. You'll see a form:

Import from: owner/repo Filters:

• State: open, closed, or both
• Labels: optional filter (e.g., bug, feature)
• Since: optional date filter

Click Import. AACWorkflow:

1. Fetches matching issues from GitHub via the GitHub App token
2. For each issue that doesn't already have a mapping, creates an AACWorkflow issue
3. Records the mapping in the external_issue table
4. Returns { imported: 42, skipped: 0, mappings: [...] }

Step 2: Review mappings

Go to Settings → GitHub → Issue Mappings. You'll see a table of all synced issues:

Click any row to:

• View the back-link to the GitHub issue
• Pause/resume sync for that issue
• Manually trigger a sync now

Two-way sync

Sync directions

GitHub → AACWorkflow (webhook): When a GitHub issue is edited, GitHub sends a webhook. AACWorkflow applies the changed fields (title, description, state) to the mapped AACWorkflow issue.

AACWorkflow → GitHub (worker): When an AACWorkflow issue is updated, a background worker debounces the change and PATCHes the GitHub issue.

Periodic reconcile: Every 30 minutes, AACWorkflow checks for issues that haven't synced recently (e.g., missed webhooks) and reconciles them.

Conflict resolution

If both GitHub and AACWorkflow changed since the last sync, the conflict is resolved using the workspace's sync strategy:

Important: When a conflict is resolved, the losing value is not lost — it's recorded in an audit comment on the AACWorkflow issue:

Synced from GitHub: Title changed from "Add OAuth" to "Add OAuth 2.1"
(AACWorkflow version: "Add OAuth" was overwritten by GitHub at 2025-06-22 15:30 UTC)

Example: Simultaneous edits

Scenario: You edit the title in AACWorkflow while a team member edits the same issue on GitHub.

1. AACWorkflow title: "Fix login timeout" → "Fix auth timeout" (you changed it)
2. GitHub title: "Fix login timeout" → "Fix login session bug" (team member changed it)
3. Both changes arrive within the reconcile window

Resolution (assuming newest_wins):

• GitHub updated_at: 2025-06-22 15:30:00
• AACWorkflow updated_at: 2025-06-22 15:29:45
• Result: GitHub version wins → AACWorkflow title becomes "Fix login session bug"
• Audit trail: An audit comment records the conflict and what was overwritten

Pause / Resume sync

To stop syncing a specific issue (e.g., you're doing detailed work in AACWorkflow and don't want GitHub changes to interfere):

1. Go to Settings → GitHub → Issue Mappings
2. Click the issue row
3. Toggle Sync enabled → OFF

Syncing is paused for that issue only. Other issues continue syncing normally.

To resume:

1. Toggle Sync enabled → ON
2. Click Sync now to reconcile immediately

Disconnect workflow

If you disconnect the GitHub App from your workspace:

1. All external_issue mappings are cascaded and deleted
2. AACWorkflow issues remain (they are not deleted)
3. Back-links are removed from issue pages
4. The historical audit trail is kept for compliance

If you reconnect later, you'll need to re-import to rebuild mappings.

API

Example: Import via API

curl -X POST https://aacworkflow.example.com/api/workspaces/my-ws/github/issues/import \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_owner": "my-org",
    "repo_name": "my-repo",
    "filters": {
      "state": "open",
      "labels": ["bug"],
      "since": "2025-01-01T00:00:00Z"
    }
  }'

Returns:

{
  "imported": 12,
  "skipped": 0,
  "mappings": [
    {
      "external_issue_id": "...",
      "issue_id": "...",
      "gh_issue_number": 123,
      "html_url": "https://github.com/my-org/my-repo/issues/123",
      "sync_enabled": true
    }
  ]
}

Security

• All queries filter by workspace_id — no cross-workspace data leakage
• Webhook signatures are verified before processing
• Installation tokens are never exposed to the client
• Assignee sync only maps verified workspace members (never creates invites)

Non-goals (future versions)

The following are intentionally NOT supported in v1:

• Importing GitHub Projects (boards), milestones, or labels as first-class objects
• Real-time comment sync (separate spec: github-pr-comments-sync.md)
• Creating brand-new GitHub issues from AACWorkflow (export is limited to issues that were imported)

Troubleshooting

"Import failed: permission denied"

You likely don't have admin permissions in the workspace. Only workspace admins can trigger import.

"Some issues were skipped (synced 40, skipped 2)"

Skipped issues already have a mapping. Re-running import on the same repo is idempotent — previously imported issues are not re-created.

"Title changed but didn't sync to GitHub"

The sync worker runs every 30 seconds (debounced). If the change hasn't synced within 5 minutes:

1. Go to Settings → GitHub → Issue Mappings
2. Click the issue row
3. Click Sync now to force an immediate reconcile
4. Check the audit log for errors

"Conflict keeps happening with the same issue"

You might be editing the issue on both sides frequently. Consider:

1. Setting sync strategy to aac_wins to prioritize AACWorkflow
2. Pausing sync while doing bulk edits, then resuming
3. Using only one side for edits while the integration stabilizes