Github Project Board

GitHub Project Board CLI Skill

Use the GitHub CLI (gh) to manage issues and pull requests on a GitHub Projects (V2) board.

Prerequisites

• gh CLI installed and authenticated.

• project OAuth scope is required for project operations. If project commands fail with permission errors, run:

  gh auth refresh -s project
  

Common Commands

Find a project

gh project list --owner <owner>

Use the numeric project number (e.g., 1) for most commands.

Add an issue or PR to a project

gh project item-add <project-number> --owner <owner> --url <issue-or-pr-url>

Example:

gh project item-add 1 --owner elodhorvath --url https://github.com/elodhorvath/LMS-Extract/pull/180

List project items

gh project item-list <project-number> --owner <owner> --format json

Note: Newly added items may not appear in the default result set. Use --limit 100 to ensure recent items are returned.

gh project item-list 1 --owner elodhorvath --format json --limit 100

The JSON shape is:

{
  "items": [
    {
      "id": "PVTI_lAHOA6991M4BCx0uzgwDmkM",
      "content": {
        "type": "PullRequest",
        "url": "https://github.com/...",
        "title": "..."
      }
    }
  ]
}

Find an item ID by URL

gh project item-list <project-number> --owner <owner> --format json --limit 100 | \
  jq -r '.items[] | select(.content.url == "<issue-or-pr-url>") | .id'

List project fields

gh project field-list <project-number> --owner <owner> --format json

The JSON shape is:

{
  "fields": [
    {
      "id": "PVTSSF_lAHOA6991M4BCx0uzg04_u8",
      "name": "Status",
      "type": "ProjectV2SingleSelectField",
      "options": [
        { "id": "f75ad846", "name": "Backlog" },
        { "id": "e18bf179", "name": "Ready" },
        { "id": "47fc9ee4", "name": "In progress" },
        { "id": "aba860b9", "name": "In review" },
        { "id": "98236657", "name": "Done" }
      ]
    }
  ]
}

Update an item's status

Use the field ID and option ID, not the human-readable names.

gh project item-edit \
  --project-id <project-id> \
  --id <item-id> \
  --field-id <status-field-id> \
  --single-select-option-id <status-option-id>

Example:

gh project item-edit \
  --project-id PVT_kwHOA6991M4BCx0u \
  --id PVTI_lAHOA6991M4BCx0uzgwDmkM \
  --field-id PVTSSF_lAHOA6991M4BCx0uzg04_u8 \
  --single-select-option-id aba860b9

ID Reference

Troubleshooting

• Permission denied / not authorized: Run gh auth refresh -s project.
• Item not found after add: Re-run item-list with --limit 100.
• unknown flag: --field: Use --field-id and --single-select-option-id instead.
• Cannot index array with string "name": field-list returns { fields: [...] }; index .fields[].
• Cannot index array with string "content": item-list returns { items: [...] }; index .items[].