Update GitHub Issue Project Status

Overview

This skill automates updating GitHub issue statuses in GitHub Projects V2. It handles single issues or batch updates for multiple issues simultaneously, managing issue assignment and project status transitions through the GitHub GraphQL API.

When to Use This Skill

Use this skill when:

• User requests updating issue status in a GitHub Project (e.g., "mark issue 17 as in progress")
• User wants to bulk-update multiple issue statuses (e.g., "mark issues 15, 16, and 17 as done")
• User needs to assign issues while updating status
• User is working with GitHub Projects V2 and needs programmatic status updates
• Local execution requires project permissions that the default token lacks

Quick Start

Prerequisites

This skill uses two separate tokens with different scopes:

1. Environment Variables Required:

``bash export GITHUBPROJECTPAT="ghpxxxx" # Classic PAT with project scope (required) export GITHUBPAT="githubpatxxxx" # Fine-grained PAT with repo scope (optional) ``

1. Token Scopes:

- GITHUBPROJECTPAT (classic PAT) - Requires project scope for project operations - GITHUB_PAT (fine-grained PAT) - Requires repo scope for issue assignment (optional)

1. Why Two Tokens?

GitHub doesn't provide a single token type that supports both project and repository operations: - Classic PATs can have project scope but can't be fine-grained to a single repo - Fine-grained PATs can be repo-specific with repo scope but don't support project scope

The script uses GITHUBPROJECTPAT for all project operations and GITHUB_PAT for issue assignment.

1. Setup Location:

Configure in .devcontainer/.env (gitignored): ``bash GITHUBPROJECTPAT=yourclassictokenhere GITHUBPAT=yourfinegrainedtokenhere ``

Basic Usage

# Update single issue to in_progress
./scripts/update-issue-status.sh 17 in_progress codekiln

# Update single issue to done
./scripts/update-issue-status.sh 17 done

# Batch update multiple issues
./scripts/update-issue-status.sh 15,16,17 done

# Set issue back to todo
./scripts/update-issue-status.sh 17 todo

Task Workflows

Task 1: Update Single Issue Status

When user requests updating a single issue:

1. Verify environment setup:

```bash # Check if required token is set if [ -z "$GITHUBPROJECTPAT" ] && [ -z "$GHPROJECTPAT" ]; then echo "Need to set GITHUBPROJECTPAT or GHPROJECTPAT" fi

# Check if optional token is set (for assignment) if [ -z "$GITHUBPAT" ]; then echo "Note: GITHUBPAT not set - issue assignment will be skipped" fi ```

1. Execute the script:

``bash cd /workspace/.claude/skills/update-github-issue-project-status ./scripts/update-issue-status.sh <issue_number> <status> [assignee] ``

1. Status values:

- todo - Move to Todo column - in_progress - Move to In Progress column (optionally assign) - done - Move to Done column

1. Example scenarios:

- User: "Mark issue 17 as in progress and assign to me" ``bash ./scripts/update-issue-status.sh 17 in_progress codekiln ``

- User: "Set issue 17 status to done" ``bash ./scripts/update-issue-status.sh 17 done ``

Task 2: Batch Update Multiple Issues

When user requests updating multiple issues at once:

1. Format issue numbers as comma-separated list:

``bash ./scripts/update-issue-status.sh 15,16,17 done ``

1. The script will:

- Process each issue sequentially - Report progress for each issue - Provide summary of successes and failures - Exit with error code if any updates failed

1. Example output:

``` Updating issue #15... ✓ Successfully updated issue #15

Updating issue #16... ✓ Successfully updated issue #16

Updating issue #17... ✓ Successfully updated issue #17

================================ Summary: ✓ Successful: 3 ================================ ```

Task 3: Troubleshooting Authentication

When the script fails with permission errors:

1. Check token availability:

``bash echo "GITHUBPROJECTPAT: ${GITHUBPROJECTPAT:0:10}..." echo "GITHUBPAT: ${GITHUBPAT:0:10}..." ``

1. Verify token scopes:

GITHUBPROJECTPAT (required): - Type: Classic Personal Access Token - Scope: project - Create at: https://github.com/settings/tokens

GITHUBPAT (optional, for issue assignment): - Type: Fine-grained Personal Access Token - Scope: repo (or publicrepo for public repos only) - Create at: https://github.com/settings/personal-access-tokens/new

1. Common errors and solutions:

- "Error: No project token found" → Set GITHUBPROJECTPAT or GHPROJECTPAT - "Resource not accessible by personal access token" → Token lacks required scope - "Skipping assignment (GITHUBPAT not set)" → Set GITHUBPAT if you want issue assignment - Assignment fails but project update succeeds → GITHUB_PAT is not set or lacks repo scope

Task 4: Verifying Updates

After updating issue statuses, verify the changes:

# Check issue status
gh issue view <issue_number> --json projectItems,assignees

# View project board (web UI)
# Navigate to: https://github.com/users/<owner>/projects/<project_number>

Script Details

Location

/workspace/.claude/skills/update-github-issue-project-status/scripts/update-issue-status.sh

Arguments

Environment Variables

The script uses two separate tokens for different operations:

For Project Operations (required):

1. GITHUBPROJECTPAT (recommended) - Classic PAT with project scope
2. GHPROJECTPAT (alternative name)

For Issue Assignment (optional):

• GITHUB_PAT - Fine-grained PAT with repo scope

Repository:

• Hardcoded to codekiln/langstar in the script

What the Script Does

1. Validates environment - Ensures required tokens are set
2. Processes each issue:

- Assigns issue using GITHUBPAT (if status is inprogress, assignee provided, and token available) - Retrieves issue node ID via GraphQL using GITHUBPROJECTPAT - Finds existing project item or adds issue to project using GITHUBPROJECTPAT - Updates project status field via GraphQL mutation using GITHUBPROJECTPAT

1. Reports results - Shows success/failure for each issue with summary

Script Behavior

• Idempotent - Safe to run multiple times with same parameters
• Automatic project addition - Adds issues to project if not already present
• Atomic per issue - Each issue update is independent
• Error handling - Continues processing remaining issues if one fails
• Exit code - Returns non-zero if any updates failed

Project Configuration

Hardcoded Project IDs

The script contains hardcoded IDs for the langstar project:

PROJECT_ID="PVT_kwHOAAImgs4BGe4B"
STATUS_FIELD_ID="PVTSSF_lAHOAAImgs4BGe4Bzg3g-NQ"
STATUS_TODO="f75ad846"
STATUS_IN_PROGRESS="47fc9ee4"
STATUS_DONE="98236657"

Updating for Different Projects

To use this skill with a different GitHub Project:

1. Find your project IDs - See references/project-configuration.md for GraphQL queries
2. Edit the script - Update the ID constants at the top of scripts/update-issue-status.sh
3. Test with a single issue - Verify before batch updates

For detailed instructions on finding these IDs, load references/project-configuration.md into context.

Integration with GitHub Actions

This skill complements the automated GitHub Actions workflow:

• GitHub Actions - Automatically updates status when @claude is mentioned or issue closes
• This Skill - Manually update statuses for any issue(s) at any time

The script uses the same logic as the GitHub Actions automation but provides manual control and batch capabilities.

Common Use Cases

Use Case 1: Starting Work on an Issue

User says: "I'm starting work on issue 17"

Execute:

./scripts/update-issue-status.sh 17 in_progress $USER

Use Case 2: Closing Multiple Related Issues

User says: "Mark issues 15, 16, and 17 as done"

Execute:

./scripts/update-issue-status.sh 15,16,17 done

Use Case 3: Resetting Issue Status

User says: "Move issue 17 back to todo"

Execute:

./scripts/update-issue-status.sh 17 todo

Use Case 4: Project Board Cleanup

User says: "All issues in the 20-25 range are done"

Execute:

./scripts/update-issue-status.sh 20,21,22,23,24,25 done

Tips for Effective Usage

1. Set both tokens - Set GITHUBPROJECTPAT (required) and GITHUB_PAT (optional for assignment)
2. Check environment first - Verify tokens are set before running
3. Test with single issue - Validate configuration before batch updates
4. Use batch updates carefully - Double-check issue numbers in comma-separated lists
5. Assignment requires GITHUB_PAT - Project updates work without it, but assignment needs it
6. Verify after updates - Use gh issue view to confirm changes
7. Keep project IDs updated - If project is recreated, update the script IDs

References

This skill includes reference documentation:

• references/project-configuration.md - Detailed project configuration, API usage, and how to find/update project IDs

Load reference files into context when needing detailed configuration information or troubleshooting guidance.