Lantern

Appearance

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:

bash
# 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 ​

bash
# 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:

bash
# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

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

"Not logged in" ​

Authenticate:

bash
gh auth login

"GH_PAT not found" ​

Set your token:

bash
# 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:

bash
# 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:

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

bash
# 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:

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

Manual Testing ​

Test Issue Linking ​

bash
# 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 ​

bash
# 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:

bash
# 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 ​

Built with VitePress

Copyright © 2026 Lantern