eia-github-integration

name	eia-github-integration
description	Use when integrating GitHub Projects. Trigger with GitHub sync, label setup, or PR workflow requests.
license	Apache-2.0
compatibility	Requires GitHub CLI version 2.14 or higher, GitHub account with write permissions to target repositories, and basic Git knowledge. Requires AI Maestro installed.
metadata	{"author":"Emasoft","version":"1.0.0"}
agent	api-coordinator
context	fork
workflow-instruction	support
procedure	support-skill
user-invocable	false

GitHub Integration Dispatcher

Overview

This skill is the entry point for all GitHub integration tasks in agent orchestration workflows. It routes you to specialized skills based on your task type. Use this skill to determine which specialized GitHub skill to invoke.

Prerequisites

Before using any GitHub integration skill, ensure:

1. GitHub CLI version 2.14 or higher is installed (gh --version)
2. GitHub CLI is authenticated (gh auth status)
3. You have write permissions to the target repository
4. Basic familiarity with Git commands

First-time setup:

# Install GitHub CLI
brew install gh   # macOS
# or see https://cli.github.com/manual/installation for other platforms

# Authenticate
gh auth login

# Verify authentication
gh auth status

For detailed setup instructions, see references/prerequisites-and-setup.md.

Decision Tree: Which Skill to Use?

Use this decision tree to route to the appropriate specialized skill:

I need to work with Pull Requests

→ Use eia-github-pr-workflow

This skill covers:

• Creating pull requests linked to issues
• PR status monitoring and CI/CD integration
• Merge strategies (squash, merge commit, rebase)
• Auto-merge configuration
• PR workflow automation

I need to sync with GitHub Projects V2

→ Use eia-github-projects-sync

This skill covers:

• Bidirectional synchronization between agent tasks and GitHub Projects V2
• Creating and configuring project boards
• Status column management (Backlog, Todo, In Progress, AI Review, Human Review, Merge/Release, Done, Blocked)
• Custom field configuration (Priority, Due Date, Effort)
• Automation rules (auto-add, auto-archive, status transitions)
• Conflict resolution and sync health monitoring

I need to orchestrate Kanban board operations

→ Use eia-kanban-orchestration

This skill covers:

• Managing the 9-label classification system (feature, bug, refactor, test, docs, performance, security, dependencies, workflow)
• Issue lifecycle management across Kanban columns
• Label-based filtering and reporting
• Kanban-specific automation patterns

I need to use Git worktrees for parallel work

→ Use eia-git-worktree-operations

This skill covers:

• Creating and managing Git worktrees for parallel feature development
• Worktree-based PR workflows
• Cleanup and maintenance of worktrees

I need to perform GitHub API operations

→ See references/api-operations.md

This reference covers:

• Direct GitHub API calls (REST and GraphQL)
• Authentication methods (token, app, OAuth)
• Rate limiting and pagination
• Webhook configuration
• Advanced query patterns

I need to manage multiple GitHub identities

→ See references/multi-user-workflow.md

This reference covers:

• SSH key setup for multiple accounts
• SSH host aliases configuration
• GitHub CLI multi-account authentication
• Identity switching and repository configuration
• Using the gh_multiuser.py script for automated identity management

Batch Operations (Unique to This Skill)

When you need to perform operations that span multiple GitHub areas (e.g., bulk label changes across issues AND PRs, or cross-project synchronization):

Batch Label Operations

Reference: references/batch-operations.md

Use when:

• Updating labels on multiple issues simultaneously
• Bulk closing stale issues
• Filtering by multiple criteria (label + status + assignee + date)
• Previewing changes before executing (dry-run mode)
• Creating audit trails for batch operations

Quick example:

# Bulk add label to all open issues with "feature" label
gh issue list --label "feature" --state open --json number --jq '.[].number' | \
  xargs -I {} gh issue edit {} --add-label "priority:high"

Automation Scripts

Reference: references/automation-scripts.md

Use when:

• Syncing GitHub Projects V2 with agent tasks (sync-projects-v2.py)
• Bulk assigning labels at scale (bulk-label-assignment.py)
• Monitoring PR status and CI/CD failures (monitor-pull-requests.py)
• Importing issues from CSV/JSON (bulk-create-issues.py)
• Generating project status reports (generate-project-report.py)

Instructions

1. Verify that GitHub CLI version 2.14 or higher is installed by running gh --version in your terminal.
2. Confirm authentication status with gh auth status. If not authenticated, run gh auth login and follow the prompts.
3. Identify your task type by consulting the Decision Tree section above (Pull Requests, Projects V2, Kanban, Worktrees, API Operations, or Multi-User).
4. Navigate to the specialized skill indicated by the decision tree (e.g., eia-github-pr-workflow for PR tasks).
5. If your task spans multiple areas (e.g., bulk label changes across issues and PRs), use the Batch Operations section in this skill directly.
6. For batch operations, always run a dry-run first by previewing the affected items with gh issue list or gh pr list before executing changes.
7. After completing your GitHub operation, verify the result by checking the repository state (e.g., gh issue view <number>, gh pr status).
8. If errors occur, consult the Error Handling section below or the detailed references/troubleshooting.md.

Checklist

Copy this checklist and track your progress:

• Verify GitHub CLI version 2.14+ is installed: gh --version
• Confirm authentication: gh auth status
• Identify task type from the Decision Tree (PR, Projects V2, Kanban, Worktrees, API, Multi-User)
• Navigate to the specialized skill or use Batch Operations if task spans multiple areas
• For batch operations: run dry-run preview first (gh issue list or gh pr list)
• Execute the GitHub operation using the appropriate skill or batch command
• Verify the result by checking repository state (gh issue view, gh pr status)
• If errors occurred, consult Error Handling section or references/troubleshooting.md

Output

This skill produces the following outputs depending on the operation performed:

• Routing decision: The name of the specialized skill to invoke (e.g., eia-github-pr-workflow, eia-github-projects-sync).
• Batch operation results: A summary of affected items (issue numbers, PR numbers) and the changes applied (labels added/removed, statuses changed).
• Automation script output: JSON or plain-text reports from the Python automation scripts (e.g., generate-project-report.py produces a Markdown status report).
• Verification output: Confirmation messages from gh CLI commands showing the current state of issues, PRs, or project boards after modifications.
• Dry-run previews: Lists of items that would be affected by a batch operation, displayed before execution for review.

Error Handling

Error	Cause	Resolution
gh: command not found	GitHub CLI is not installed or not in PATH	Install with brew install gh (macOS) or see references/prerequisites-and-setup.md
HTTP 401 - Bad credentials	Authentication token expired or revoked	Re-authenticate with gh auth login and verify with gh auth status
HTTP 403 - Resource not accessible	Insufficient permissions on the target repository	Request write access from the repository owner, or check that your token has the required scopes (repo, project)
HTTP 422 - Validation Failed	Invalid field values (e.g., non-existent label name, malformed project field)	Verify the label exists with gh label list or check project field names with gh project field-list
API rate limit exceeded	Too many API calls in a short period	Wait for the rate limit reset (check gh api rate-limit), or use GraphQL to batch multiple queries into one request
Could not resolve to a Project	Wrong project number or the project is in a different organization	Verify the project number with gh project list --owner <org> and ensure you are targeting the correct owner
xargs: gh: terminated by signal 13	Pipe broken during batch operation, often due to API errors mid-stream	Re-run the batch operation with smaller batch sizes or add error handling with `xargs -I {} sh -c 'gh issue edit {} --add-label "label"

Examples

Example 1: Route to the correct skill for a PR task

You receive a request: "Create a PR for the feature branch and link it to issue #42." This is a Pull Request task. According to the decision tree, invoke eia-github-pr-workflow:

# Switch to eia-github-pr-workflow skill, then run:
gh pr create --base main --head feature-branch --title "Implement feature X" \
  --body "Closes #42" --assignee "@me"

Example 2: Bulk add a label to all open bug issues

You need to add the priority:critical label to all issues labeled bug that are currently open:

# Step 1: Preview affected issues (dry-run)
gh issue list --label "bug" --state open --json number,title --jq '.[] | "\(.number): \(.title)"'

# Step 2: Apply the label change
gh issue list --label "bug" --state open --json number --jq '.[].number' | \
  xargs -I {} gh issue edit {} --add-label "priority:critical"

# Step 3: Verify a sample issue
gh issue view 15 --json labels --jq '.labels[].name'

Example 3: Check which skill to use for a Projects V2 sync request

You receive a request: "Sync the agent task board with the GitHub Project for repository X." This is a GitHub Projects V2 synchronization task. According to the decision tree, invoke eia-github-projects-sync:

# Verify the project exists first
gh project list --owner Emasoft --format json

# Then follow the eia-github-projects-sync skill instructions for bidirectional sync
uv run python scripts/sync-projects-v2.py --repo Emasoft/repo-x --project 3 --direction bidirectional

Troubleshooting

If you encounter issues with any GitHub integration task, see references/troubleshooting.md for:

• Authentication failures and re-authentication
• Projects V2 synchronization issues
• Pull request linking problems
• Label system issues
• GitHub CLI installation and PATH issues
• API rate limiting
• Webhook delivery failures

Resources

Core References:

• references/prerequisites-and-setup.md - GitHub CLI installation and authentication
• references/multi-user-workflow.md - Managing multiple GitHub identities
• references/api-operations.md - Direct API operations
• references/batch-operations.md - Bulk operations and filtering
• references/automation-scripts.md - Python automation scripts
• references/troubleshooting.md - Common issues and solutions

Specialized Skills:

• eia-github-pr-workflow - Pull request operations
• eia-github-projects-sync - Projects V2 bidirectional synchronization
• eia-kanban-orchestration - Kanban board and 9-label system management
• eia-git-worktree-operations - Git worktree management

---

Skill Version: 2.0.0 Last Updated: 2026-02-05 Maintainer: Skill Development Team Changelog:

• 2.0.0: Refactored as thin dispatcher to specialized skills, removed duplicated content
• 1.2.0: Added cross-platform gh_multiuser.py script with configuration-driven identity management
• 1.1.0: Added Multi-User Workflow reference for owner/developer identity separation