Bootstrapping Github Projects

Bootstrapping GitHub Projects

Bootstrap a GitHub Projects V2 board with standardized custom fields, views, and automations using a proven project management template.

What you should do

When invoked, set up a GitHub project using the automation script. Manual steps are only required for view creation (no API support).

Automated setup (Primary approach)

Run the automation script from the repository root. The script auto-detects the repository from git context:

# Auto-detect repository from current git directory
./core/skills/gh-project-setup/scripts/setup-project.sh

# Or specify repository explicitly (if not in git directory)
./core/skills/gh-project-setup/scripts/setup-project.sh owner/repo [project-name]

The script automatically:

• ✅ Detects repository from git remote (or uses provided argument)
• ✅ Verifies GitHub authentication and project scope
• ✅ Gets current user as owner
• ✅ Creates project (derives name from repo if not provided)
• ✅ Creates/updates custom fields (Status, Value, Effort)
• ✅ Links repository to project
• ✅ Creates semantic repository labels
• ✅ Saves configuration to .github/project-config.json

Configuration file location: The config is saved to .github/project-config.json (NOT docs/):

• Standard GitHub-specific configuration directory
• Alongside workflows, issue templates, and other automation
• Separates infrastructure config from user documentation
• Used by gh-project-manage skill for efficient automation

Manual step required: Create views via web UI (no API available)

Manual setup

For step-by-step instructions or if the automation script cannot be used, see MANUAL-SETUP.md.

Example workflow

User invokes skill: /gh-project-setup in Claude Code (from repository root)

Agent executes:

1. Run automation script: ./core/skills/gh-project-setup/scripts/setup-project.sh
2. Script auto-detects repository and handles everything (auth, project, fields, labels, config)
3. Instruct user to create views manually via web UI (provide project URL from script output)
4. Output summary with project URL and next steps (automations, testing)

Error handling

Common issues:

1. Missing project scope

   gh auth refresh -h github.com -s project
   

2. Organization not found

   • Verify org name
   • Check user has admin access

3. Repository not found

   • Verify repo exists
   • Check format is owner/repo

4. GraphQL errors

   • Check API response for specific error messages
   • Verify all IDs are correct format

5. Field creation fails - Missing description

   Error: Expected value to not be null for description field

   Solution: Every option MUST include a description property:

   {"name": "Todo", "color": "GREEN", "description": "Ready to start"}
   

6. Field creation fails - JSON array stringified

   Error: Expected "..." to be a key-value object

   Solution: Don't use -F flags for JSON arrays. Use --input with a JSON file instead.

7. Cannot update field options

   Solution: Use updateProjectV2Field mutation (requires December 2024+ API version)

Integration with existing tools

Works with:

• gh-project-manage skill - Use generated config for ongoing management
• git-project-setup workflow - Reference documentation for process
• git-issue-create agent - Auto-add new issues to project
• Issue templates - Update to reference project fields

Generated config enables:

# Example: Add issue to project and set fields using gh-project-manage
gh project item-add <number> --owner <org> --url <issue-url>

# Set fields using IDs from config file
gh project item-edit --id <item-id> --project-id <project-id> \
  --field-id <status-field-id> --single-select-option-id <todo-option-id>

Customization options

If advanced customization is needed after initial setup, use the gh-project-manage skill to:

• Update custom field options
• Modify automations
• Change label definitions
• Manage project views

Best practices

1. Align project name with repository name - Matches repository slug for consistency
2. Always save configuration file - Essential for future management with gh-project-manage
3. Use --input flag for all field mutations - The -F flag doesn't work for JSON arrays
4. Always include description in options - Required by API schema
5. Verify auth and project scope upfront - Check with gh auth status
6. Create standard labels automatically - Apply semantic color psychology for consistency
7. Test immediately - Create test issue and add to project
8. Capture all field and option IDs - Store in config file for future automation

Reference: Standard template

Custom fields (semantic colors):

• Status: Backlog (GRAY) → Todo (GREEN) → Doing (BLUE) → Done (PURPLE)
  • Color progression: neutral → ready → active → complete
• Value: Essential (PURPLE) > Useful (BLUE) > Nice-to-have (GREEN)
  • Color hierarchy: highest priority uses most vibrant color
• Effort: Heavy (RED) > Moderate (YELLOW) > Light (GRAY)
  • Color warning: red = significant investment, gray = quick task

Views:

• Status board (primary workflow view)
• Table (detailed planning view)
• Value board (prioritization view)
• Effort board (capacity planning view)

Automations:

• Auto-add sub-issues
• Auto-close on PR merge
• Set Status=Done on item closed
• Set Status=Done on PR merged

Label color philosophy:

• Warm colors (red-orange): Urgency and attention-required items
• Cool colors (blue-cyan): Technical infrastructure and routine work
• Greens: Quality and success indicators
• Purples: Refinement and improvement work
• Grays: Neutral configuration and documentation

For detailed color assignment guidance, see LABEL-COLORS.md.

Planning philosophy:

• Value/Effort guide prioritization (not arbitrary priority labels)
• Status reflects work state, dependencies reflect constraints
• Backlog is for triage, Todo is ready queue
• Done means merged and deployed

API reference and troubleshooting

For detailed API information, limitations, and technical notes, see REFERENCE.md:

• GitHub CLI -F flag limitations and workarounds
• Required field properties and schemas
• updateProjectV2Field mutation details (December 2024+)
• GraphQL mutation reference
• Available colors for field options
• View creation limitations
• Built-in automation capabilities