Testing: GitHub Projects V2 Integration

Complete testing guide for GitHub Projects V2 automation.

Workflow: issue-automation.yml

Quick Start

Prerequisites

• GitHub CLI (gh) installed
• GitHub PAT with repo + project scopes
• jq installed (for JSON parsing)

Setup Your PAT

See TESTING_API_KEY_SETUP.md for detailed setup.

Quick version:

# 1. Create PAT at: https://github.com/settings/tokens
#    Scopes: repo, project
#    Copy the token

# 2. Add to .env.local
echo "GH_PAT=ghp_YOUR_TOKEN_HERE" >> .env.local

Run Tests

# Option 1: Using .env.local (easiest)
./.github/workflows/test-projects-v2.sh

# Option 2: Using environment variable
GH_PAT=ghp_YOUR_TOKEN_HERE bash ./.github/workflows/test-projects-v2.sh

What Gets Tested

The test script validates:

✅ Project Discovery

• Searches repository → organization → user projects (in that order)
• Finds project by exact name match ("Lantern App")
• Returns correct project ID

✅ Field Names

• Verifies "Status" field exists (case-sensitive)
• Confirms "In progress" status option exists
• Checks "Start date" field exists

✅ API Connectivity

• GitHub API authentication works
• GraphQL endpoint responds
• PAT has sufficient permissions

✅ Issue Linking

• Can add issue to project
• Can set Status field
• Can set Start date field

Expected Output

✅ GitHub CLI authenticated
✅ jq is installed
✅ Testing project discovery...
✅ Project "Lantern App" found (ID: PVT_...)
✅ Found 2 fields: Status, Start date
✅ Testing issue linking...
✅ Successfully linked test issue to project
✅ Successfully set Status = "In progress"
✅ Successfully set Start date = 2026-01-16

All tests passed!

Troubleshooting

"gh command not found"

Install GitHub CLI:

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Or visit: https://cli.github.com

"Not logged in"

Authenticate:

gh auth login

"GH_PAT not found"

Set your token:

# Option 1: Add to .env.local
echo "GH_PAT=ghp_YOUR_TOKEN_HERE" >> .env.local

# Option 2: Export environment variable
export GH_PAT="ghp_YOUR_TOKEN_HERE"

# Option 3: Create .github/workflows/.env.local
echo "GH_PAT=ghp_YOUR_TOKEN_HERE" >> .github/workflows/.env.local

"jq not installed"

Install JSON processor:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Or visit: https://stedolan.github.io/jq/download/

"Project 'Lantern App' not found"

Check:

1. Project exists: Go to https://github.com/cattreedev/lantern_app/projects
2. Correct name: Must be exactly "Lantern App" (case-sensitive)
3. Correct scope: Repository-level projects checked first
4. Permissions: PAT has project scope

Debugging:

# List projects script can find
gh project list --owner cattreedev --format json | jq .
gh api graphql -f query='query {
  organization(login:"cattreedev") {
    projectsV2(first:10) { nodes { title } }
  }
}'

"Insufficient permissions"

Your PAT needs scopes: repo + project

# Check current token scopes
gh auth status

# Create new token with correct scopes
# https://github.com/settings/tokens
# Scopes: repo, project

"Field 'Status' not found"

Your project might have different field names.

Debug what fields exist:

gh api graphql -f projectId="PVT_YOUR_ID" -f query='query {
  projectV2(id: $projectId) {
    fields(first: 20) {
      nodes { name }
    }
  }
}'

Manual Testing

Test Issue Linking

# Create a test issue
gh issue create \
  --title "Test Issue #$(date +%s)" \
  --body "This is a test issue for Projects V2" \
  --repo cattreedev/lantern_app

# Get the issue number from output, e.g., #999

# Link it to the project manually
gh api graphql -f query='mutation {
  addProjectV2ItemById(input: {
    projectId: "PVT_..."
    contentId: "I_..."  # Issue GraphQL ID
  }) { item { id } }
}'

Test Field Updates

# Update Status field
gh api graphql -f query='mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_..."
    itemId: "PVTI_..."
    fieldId: "PVTF_..."
    value: { singleSelectOptionId: "OPTION_ID" }
  }) { projectV2Item { id } }
}'

Current Configuration

Project Name: Lantern App (case-sensitive)
Fields:

• Status: with options ["In progress", "Todo", "Done"]
• Start date: date field

Workflow Triggers:

• Issue assigned
• Branch/PR created referencing issue
• Issue reopened

Workflow Actions:

• Adds issue to project
• Sets Status = "In progress"
• Sets Start date = today

How the Workflow Works

File: .github/workflows/issue-automation.yml

1. Issue Event: Someone creates/assigns an issue
2. Extract Issue Number: From PR title, branch name, or description
3. Find Project: Searches repository → organization → user projects
4. Link Issue: Adds issue to "Lantern App" project
5. Set Fields: Status → "In progress", Start date → today
6. Comment: Posts confirmation comment (if error, posts error details)

Testing Locally Before Deployment

Important: Always run local tests before deploying workflow changes:

# 1. Set up your PAT
echo "GH_PAT=ghp_YOUR_TOKEN_HERE" >> .env.local

# 2. Run the test script
./.github/workflows/test-projects-v2.sh

# 3. Verify all tests pass

# 4. Now safe to deploy to production

Cost

GitHub Projects V2 API is FREE for repository projects.

✅ Unlimited issues
✅ Unlimited field updates
✅ Unlimited API calls

See Also

• API Key Setup - GitHub PAT setup
• Workflows Overview - All workflows
• GitHub Projects V2 Documentation
• GitHub GraphQL API
• Troubleshooting Guide - Advanced troubleshooting