emasoft/amia-github-projects-sync

GitHub Projects Sync

Overview

Manages team tasks through GitHub Projects V2 via GraphQL API — READ + STATUS UPDATE ONLY.

Prerequisites

• GitHub CLI (gh) authenticated with project scope
• GitHub Projects V2 enabled repository
• Python 3.8+ for automation scripts

Instructions

1. Authenticate — verify with gh auth status (needs project scope)
2. Locate project — find project ID via GraphQL query (see Examples)
3. Execute — use gh api graphql or run automation scripts
4. Verify — check project board or query API to confirm changes
5. Notify — send AI Maestro messages to relevant agents if needed

Checklist

Copy this checklist and track your progress:

• [ ] Verify GitHub CLI auth with project scope
• [ ] Locate project using GraphQL queries
• [ ] Execute via GraphQL API or automation scripts
• [ ] Verify result on project board or via API
• [ ] Notify stakeholders via AI Maestro if needed
• [ ] Document change in issue comments or task lists

Output

| Output Type | Format | Description | |-------------|--------|-------------| | Project item IDs | JSON | GraphQL node IDs for created/updated items | | Status updates | JSON | Confirmation of field value changes | | Issue metadata | JSON | Issue numbers, titles, states, assignees | | Project reports | Markdown | Status summaries, progress updates | | Sync logs | Text/JSON | Automation script execution results | | Error details | JSON/Text | API errors, validation failures, rate limits |

Output discipline: All scripts support --output-file <path>. Use it in automated workflows to minimize token consumption.

Reference Documents

See references/ directory for all reference documents.

Error Handling

Script failures return non-zero exit codes. See error-handling for details:

• When encountering GitHub API errors
• When hitting rate limits
• When project or item is not found
• When item updates fail
• When authentication fails
• When webhook delivery fails
• When implementing retry logic

Examples

Example 1: Find Your Project

gh api graphql -f query='
  query {
    repository(owner: "OWNER", name: "REPO") {
      projectsV2(first: 10) {
        nodes { id title number }
      }
    }
  }
'

Resources

Full reference: detailed-guide:

• Critical Distinction
• When to Invoke
• Iron Rules Compliance
• Issue Lifecycle Policy
• AI Maestro Integration
• Threshold Configuration
• Error Handling Details
• Status Columns
• Reference File Contents Index