Add an Issue or PR to a GitHub Project

Triage happens in the issue tracker, but the plan lives on the project board, and gh project item-add is the bridge between them. This guide adds an existing GitHub issue or pull request to a project and checks the result from the command's own response. Allow about five minutes if you already know the project number and item URL. The examples use GitHub CLI 2.87.3, installed on this machine; check your own version before relying on output details.

1. Check the command and authentication

This is an online GitHub operation. It changes project contents, so use the account and project you actually intend to change. You need GitHub CLI installed and authenticated with permission to update the destination project. No root access is needed, and adding an item does not require sudo.

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh project item-add --help

Your version will probably differ; the help output is the local authority for available flags. If authentication is uncertain, check it without changing project data:

$ gh auth status

2. Identify the project number and item URL

• The positional argument is the project number, not an issue number. They are separate identifiers: project 7 and issue 23 can appear together in a command, but 23 is not the project number.
• --owner identifies the login that owns the project. The manual allows @me for the current user.
• --url is the full URL of the issue or pull request to add.

$ gh project item-add 7 \
    --owner EXAMPLE_OWNER \
    --url https://github.com/EXAMPLE_OWNER/EXAMPLE_REPO/issues/23

Replace every uppercase placeholder. For a pull request, use its /pull/NUMBER URL instead. The command accepts an issue or a pull request URL; it does not create either one.

3. Review the change before running it

The command has no confirmation prompt in its documented usage, so read the complete line before pressing Enter, especially the project number, owner and repository path. Adding an item is reversible, but it is still a remote state change, and the wrong project can be easy to miss in a busy workspace.

There is no dry-run flag in this command's installed help. For a final read-only check, inspect the project and item separately with the relevant gh project and gh issue or gh pr commands. Do not swap a known item URL for a guessed one.

4. Add the issue or pull request

Run the reviewed command. A successful invocation returns the newly added project item in the CLI's normal output format:

$ gh project item-add 7 --owner EXAMPLE_OWNER \
    --url https://github.com/EXAMPLE_OWNER/EXAMPLE_REPO/issues/23
$ printf '%s\n' "$?"
0

The exact human-readable response can vary with the CLI release and server response, so treat exit status zero as the success signal. If it exits non-zero, read the error before retrying: a failed request may be caused by an incorrect owner, a missing project permission, an invalid URL, or an item the account cannot see.

5. Request machine-readable output

For a script or an audit trail, ask for JSON rather than scraping human text. The installed command documents --format json, plus --jq for filtering and --template for Go templates:

$ gh project item-add 7 --owner EXAMPLE_OWNER \
    --url https://github.com/EXAMPLE_OWNER/EXAMPLE_REPO/pull/42 \
    --format json \
    --jq '{id: .id, title: .title, type: .content.type}'

Use the fields your installed release actually returns when building automation. If a filter fails because the response shape differs, remove --jq and inspect the complete JSON instead of guessing a field name:

$ gh project item-add 7 --owner EXAMPLE_OWNER \
    --url https://github.com/EXAMPLE_OWNER/EXAMPLE_REPO/issues/23 \
    --format json

Do not put access tokens or other secrets in the URL, shell history or a template. The issue or pull request URL is normally public metadata even when the project itself is restricted.

6. Verify or undo the addition

Verify the project now contains the item using its item-list command. Start with the same owner and project number, then narrow the output with its documented options if needed:

$ gh project item-list 7 --owner EXAMPLE_OWNER

Look for the issue or pull request title and confirm it belongs to the expected project.