skmuiruri

The gh project command manages GitHub Projects (v2) — flexible boards for planning and tracking work across repositories.

Required scope: You need the project token scope. Add it with:

gh auth refresh -s project

Creating a Project

# Create for your user
gh project create --title "My Roadmap"
 
# Create for an organization
gh project create --owner my-org --title "Sprint Board"

Listing Projects

# Your projects
gh project list
 
# An organization's projects
gh project list --owner my-org
 
# Limit
gh project list --limit 20
 
# JSON output
gh project list --json number,title,url

Viewing a Project

# View in terminal
gh project view 1
 
# View an org's project
gh project view 1 --owner my-org
 
# Open in browser
gh project view 1 --web
 
# JSON output
gh project view 1 --json title,readme,items

Editing a Project

gh project edit 1 --title "Updated Roadmap"
gh project edit 1 --description "Our product roadmap for Q1"
gh project edit 1 --visibility public
gh project edit 1 --readme "# Roadmap\nThis project tracks..."

Closing / Deleting a Project

gh project close 1
gh project delete 1

Copying a Project

gh project copy 1 --title "Copy of Roadmap" --target-owner my-org

Marking as Template

gh project mark-template 1
gh project mark-template 1 --undo

Managing Fields

Fields define columns and properties (Status, Priority, Sprint, etc.).

# List fields
gh project field-list 1 --owner my-org
 
# Create a field
gh project field-create 1 --owner my-org --name "Priority" --data-type "SINGLE_SELECT"
 
# Delete a field
gh project field-delete --id <field-id>

Managing Items

Items are the cards on your board — they can be issues, PRs, or draft items.

Adding Existing Issues/PRs

gh project item-add 1 --owner my-org --url https://github.com/my-org/repo/issues/42

Creating Draft Items

gh project item-create 1 --owner my-org --title "Research new API design"

Listing Items

gh project item-list 1 --owner my-org
gh project item-list 1 --owner my-org --limit 100
 
# JSON output
gh project item-list 1 --json title,type,status

Editing Items

gh project item-edit --id <item-id> --field-id <field-id> --text "Updated value"
gh project item-edit --id <item-id> --field-id <field-id> --single-select-option-id <option-id>
gh project item-edit --id <item-id> --field-id <field-id> --date "2024-03-01"

Archiving / Deleting Items

gh project item-archive 1 --id <item-id> --owner my-org
gh project item-delete 1 --id <item-id> --owner my-org

Linking Projects to Repositories

gh project link 1 --owner my-org --repo my-org/my-repo
gh project unlink 1 --owner my-org --repo my-org/my-repo

Exercises

  1. Ensure the project scope is available: gh auth refresh -s project
  2. Create a project: gh project create --title "Test Board"
  3. Add a draft item: gh project item-create 1 --title "Try this feature"
  4. List items: gh project item-list 1
  5. Close the project: gh project close 1
Previous← GistsNextCodespaces →