GitHub Projects v2 Skill#

Auth prerequisite#

bash

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 <owner> --format json | jq '.projects[] | select(.number==1) | .id'

---

1. List backlog items#

bash

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

# Filter by status — show only backlog
gh project item-list <number> --owner <owner> --query "status:Backlog"

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

# JSON output for scripting
gh project item-list <number> --owner <owner> --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.

bash

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

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

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

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

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

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

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

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

---

3. Add a comment to an issue#

bash

# Add a comment (issue number, not project item ID)
gh issue comment <issue-number> --repo <owner>/<repo> --body "Your comment here"

# From a file
gh issue comment <issue-number> --repo <owner>/<repo> --body-file comment.md

---

4. Create an issue and add it to the project#

bash

# Create issue in a repo
ISSUE_URL=$(gh issue create \
  --repo <owner>/<repo> \
  --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 <number> --owner <owner> --url "$ISSUE_URL"

---

5. Create a sub-issue#

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

bash

# 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 <parent-issue-number> \
  --repo <owner>/<repo> \
  --title "Implement login endpoint" \
  --body "POST /api/login"

# Link an existing issue as a sub-issue of a parent
gh sub-issue add <parent-issue-number> <child-issue-number> --repo <owner>/<repo>

# List sub-issues of a parent
gh sub-issue list <parent-issue-number> --repo <owner>/<repo>

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

bash

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