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 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