GitHub Projects V2 Troubleshooting Guide

Date: January 15, 2026
Status: ✅ Active

Overview

This guide provides troubleshooting information for GitHub Projects V2 integration issues in the Lantern App repository.

Common Issues

Issue 1: "Project 'Lantern App' not found"

Symptoms:

• Issue automation workflow logs show: ⚠️ Project 'Lantern App' not found
• Issues are created successfully but not added to the project
• Status and Start Date fields are not updated

Root Causes:

1. GitHub Projects V2 project doesn't exist or is archived
2. Project name doesn't match exactly (V2 projects are name-sensitive)
3. Project is in a different location (organization, user, or repository)
4. Workflow doesn't have permission to access the project

Solutions:

Step 1: Verify Project Exists

1. Go to https://github.com/cattreedev/lantern_app/projects
2. Check if a project named exactly "Lantern App" exists
3. If it exists:
   • Click to open it
   • Verify the project is not archived
   • Note the project URL (shows where it's located: organization, user, or repository)

Step 2: Find Correct Project Name

If the project exists but has a different name:

# List all organization projects (requires GitHub CLI)
gh project list --owner cattreedev

# List all user projects
gh project list --owner mechelle

# List repository projects
gh project list --owner cattreedev --repo lantern_app

Step 3: Update Workflow

If the project name differs, edit the workflow:

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

Change this line:

PROJECT_NAME: "Lantern App"

To the actual project name:

PROJECT_NAME: "Your Actual Project Name"

Issue 2: GitHub Projects V2 API Errors

Symptoms:

• GraphQL query errors in workflow logs
• null values returned for project fields
• Field updates fail silently

Root Causes:

1. Missing or misconfigured Status/Start Date fields in the project
2. GraphQL query limit exceeded (usually safe, but check query size)
3. Permission issues with workflow token

Solutions:

Verify Project Fields

1. Open the GitHub Projects V2 project
2. Click the ⚙️ Settings icon
3. Verify these fields exist:
   • Status (Single select field)
   • Start Date (Date field)
4. Verify Status has an "In Progress" option

Expected Field Configuration

Status Field:

• Type: Single select
• Options include: "In Progress", "Done", "Backlog", etc.

Start Date Field:

• Type: Date
• No specific configuration needed

Issue 3: Field Updates Not Working

Symptoms:

• Issues added to project successfully
• Status and Start Date fields not updated
• Workflow logs show "⚠️ Failed to update {field} field"

Root Causes:

1. Custom field names don't match exactly (case-sensitive)
2. Field doesn't exist in the project
3. "In Progress" option doesn't exist in Status field

Solutions:

Verify Custom Fields Match

The workflow looks for these exact field names:

• Status (capital S)
• Start Date (capital S and D, with space)

If your fields have different names, either:

1. Rename the fields to match, OR
2. Update the workflow to use the correct field names

Rename Fields (Option 1)

In GitHub Projects V2 settings:

1. Click ⚙️ Settings → Custom fields
2. For each field, click the ... menu
3. Select Rename
4. Update to exact name: Status, Start Date

Update Workflow (Option 2)

Edit .github/workflows/issue-automation.yml and update these lines:

# OLD
STATUS_FIELD_ID=$(echo "$FIELDS_DATA" | jq -r '.data.node.fields.nodes[]? | select(.name == "Status") | .id')

# NEW - If your field is named "Task Status"
STATUS_FIELD_ID=$(echo "$FIELDS_DATA" | jq -r '.data.node.fields.nodes[]? | select(.name == "Task Status") | .id')

How the Workflow Works

The issue automation workflow:

1. Detects when an issue is assigned
2. Finds the GitHub Projects V2 project by name
3. Adds the issue to the project (if not already added)
4. Sets Status to "In Progress"
5. Sets Start Date to today's date

Query Limits

The workflow now uses:

• 100 projects per search (increased from 20 to handle repos with many projects)
• 100 fields per project (standard for most projects)
• 100 items per project (increased for better performance)

These limits are safe for most repositories. If your project has significantly more items, the workflow may need adjustment.

Debugging Steps

1. Check Workflow Logs

1. Go to Actions
2. Select Issue Automation workflow
3. Find the run that failed
4. Expand the Update GitHub Project fields step
5. Look for these indicators:

Good indicators:

• ✅ Found issue
• ✅ Found project
• ✅ Status updated
• ✅ Start Date set

Warning indicators:

• ⚠️ Project not found
• ⚠️ Field not found
• ℹ️ Skipping (usually safe)

2. Manual Verification

# Test project discovery (requires GitHub CLI & auth)
gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      projectsV2(first: 100) {
        nodes { title id }
      }
    }
  }
' -f owner="cattreedev" -f repo="lantern_app"

3. Check Issue Manually

1. Go to the issue that failed
2. Click Projects on the right sidebar
3. Verify the project is listed
4. Click the project to view its details
5. Check Status and Start Date fields

Advanced Configuration

Using Environment Variables

If you want to use different project names for different workflows, add to repository secrets:

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

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  ISSUE_NUMBER: ${{ steps.get-issue.outputs.issue_number }}
  PROJECT_NAME: ${{ secrets.GITHUB_PROJECT_NAME || 'Lantern App' }}

Then add to repository secrets:

• Name: GITHUB_PROJECT_NAME
• Value: Your actual project name

Multiple Projects

If you want different issues to go to different projects, you'd need to modify the workflow to:

1. Read issue labels
2. Determine target project based on labels
3. Search for that project

This is a more complex configuration - contact the team if needed.

References

• GitHub Projects V2 API Documentation
• GitHub Projects V2 User Guide
• GitHub Actions Documentation

Related Documentation

• Issue Automation Testing Guide
• Discord Bot GitHub Projects Integration
• GitHub Workflows README

Reporting Issues

If you encounter problems:

1. Collect information:

   • Workflow run number (from Actions tab)
   • Issue number that failed
   • Complete workflow log output
   • Screenshot of project settings

2. Create an issue:

   gh issue create \
     --title "GitHub Projects V2 Issue: [Description]" \
     --body "Workflow: issue-automation.yml
   Issue Number: #XXX
   
   **Steps to reproduce:**
   1. ...
   
   **Expected behavior:**
   - ...
   
   **Actual behavior:**
   - ...
   
   **Workflow log:**
   [Paste relevant log section]"

3. Or contact the team in Discord/Slack

See Also

• TESTING_ISSUE_AUTOMATION.md - Testing procedures
• issue-automation.yml - Workflow source code
• DOCUMENTATION_SAFEGUARDS.md - Doc standards