GitHub Projects v2 Skill

Auth prerequisite

gh auth status                  # verify scopes
gh auth refresh -s project      # add project scope if missing

ID note: Most gh project commands take a project number (e.g. 1) + --owner. item-edit is the exception — it requires --project-id with the GraphQL node ID (e.g. PVT_xxx). Get it with: gh project list --owner \x3Cowner> --format json | jq '.projects[] | select(.number==1) | .id'

1. List backlog items

# List all items (default 30, use --limit to raise)
gh project item-list \x3Cnumber> --owner \x3Cowner> --limit 100

# Filter by status — show only backlog
gh project item-list \x3Cnumber> --owner \x3Cowner> --query "status:Backlog"

# Filter open issues assigned to you
gh project item-list \x3Cnumber> --owner \x3Cowner> --query "assignee:@me is:issue is:open"

# JSON output for scripting
gh project item-list \x3Cnumber> --owner \x3Cowner> --format json \
  | jq '.items[] | {id, title, status}'

2. Set fields on an item (status, iteration, priority, etc.)

item-edit requires the project node ID and item node ID — both available from item-list --format json.

# Get project node ID
PROJECT_ID=$(gh project list --owner \x3Cowner> --format json \
  | jq -r '.projects[] | select(.number==\x3Cnumber>) | .id')

# Get item IDs and current field values
gh project item-list \x3Cnumber> --owner \x3Cowner> --format json | jq '.items[]'

# Get field IDs and option IDs (needed for single-select and iteration fields)
gh project field-list \x3Cnumber> --owner \x3Cowner> --format json | jq '.fields[]'

# Set a single-select field (e.g. Status, Priority)
gh project item-edit --project-id $PROJECT_ID --id \x3Citem-node-id> \
  --field-id \x3Cfield-node-id> --single-select-option-id \x3Coption-id>

# Set an iteration field (e.g. Sprint)
gh project item-edit --project-id $PROJECT_ID --id \x3Citem-node-id> \
  --field-id \x3Cfield-node-id> --iteration-id \x3Citeration-id>

# Set a date field
gh project item-edit --project-id $PROJECT_ID --id \x3Citem-node-id> \
  --field-id \x3Cfield-node-id> --date "2025-12-31"

# Set a number field (e.g. Story Points)
gh project item-edit --project-id $PROJECT_ID --id \x3Citem-node-id> \
  --field-id \x3Cfield-node-id> --number 5

# Clear any field value
gh project item-edit --project-id $PROJECT_ID --id \x3Citem-node-id> \
  --field-id \x3Cfield-node-id> --clear

3. Add a comment to an issue

# Add a comment (issue number, not project item ID)
gh issue comment \x3Cissue-number> --repo \x3Cowner>/\x3Crepo> --body "Your comment here"

# From a file
gh issue comment \x3Cissue-number> --repo \x3Cowner>/\x3Crepo> --body-file comment.md

4. Create an issue and add it to the project

# Create issue in a repo
ISSUE_URL=$(gh issue create \
  --repo \x3Cowner>/\x3Crepo> \
  --title "Fix login timeout" \
  --body "Users are being logged out after 5 minutes." \
  --assignee "@me" \
  --label "bug")

# Add the new issue to the project
gh project item-add \x3Cnumber> --owner \x3Cowner> --url "$ISSUE_URL"

5. Create a sub-issue

Native gh issue doesn't support sub-issues yet. Use the gh-sub-issue extension:

# Install once
gh extension install yahsan2/gh-sub-issue

# Create a new issue as a sub-issue of an existing parent
gh sub-issue create --parent \x3Cparent-issue-number> \
  --repo \x3Cowner>/\x3Crepo> \
  --title "Implement login endpoint" \
  --body "POST /api/login"

# Link an existing issue as a sub-issue of a parent
gh sub-issue add \x3Cparent-issue-number> \x3Cchild-issue-number> --repo \x3Cowner>/\x3Crepo>

# List sub-issues of a parent
gh sub-issue list \x3Cparent-issue-number> --repo \x3Cowner>/\x3Crepo>

If the extension is not available, fall back to GraphQL:

gh api graphql -f query='
  mutation($parentId: ID!, $childId: ID!) {
    addSubIssue(input: { issueId: $parentId, subIssueId: $childId }) {
      issue { number title }
      subIssue { number title }
    }
  }
' -F parentId=\x3Cparent-node-id> -F childId=\x3Cchild-node-id>