project-boards

Project Boards

Read and change GitHub Projects (v2) boards: what is on one, what each card's fields say, and where an issue sits.

Prerequisites

• project_owner and project_number, both readable from the board's URL: https://github.com/users/OWNER/projects/NUMBER or https://github.com/orgs/OWNER/projects/NUMBER
• repo_owner, repo_name and issue_number for the issue or pull request
• A token that reaches Projects. This is a separate grant from repo: a classic token needs read:project to read and project to write, a fine-grained one needs Projects read and write

The board's owner is not always the repository's owner. An organisation board holding issues from several repositories is the common case, so read project_owner off the board URL rather than assuming it matches repo_owner.

Workflow

Filing an issue and placing it

1. Call create_issue as usual
2. Call get_project_fields to see which fields the board has and what each single-select one accepts
3. Call set_project_field with the field and option names. It puts the issue on the board first if it is not already there, so add_to_project is only needed when no field is being set

Triaging a backlog

1. Call list_project_items to read every card with its field values
2. Group by the fields map, for example by Status, to see what is where
3. Call set_project_field per issue to move it

Taking something off

1. Call remove_from_project
2. The issue stays open and untouched. Only the card goes, and the field values it held go with it
3. Ask the user in chat before removing a card, since the field values cannot be recovered

Tool Parameters

get_project_fields

Parameter	Type	Description
project_owner	str	User or organisation that owns the board
project_number	int	Project number, as it appears in the board's URL

Returns project_number, title, url and fields. Each field carries its id, name, data_type and options. options is empty for anything that is not a single select, which is what tells you set_project_field will refuse it.