Add an Issue or Pull Request to a GitHub Project with gh

You will add an existing GitHub issue or pull request to a project using gh project item-add, then verify the result from the command's 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 local 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 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

Checkpoint: stop here if the reported account is not the one that should own this change. Do not try a write command just to discover which account is active.

2. Identify the project number and item URL

The positional argument is the project number. The --owner value identifies the login that owns the project, and the manual allows @me for the current user. The --url value is the full URL of the issue or pull request to add.

Use the number shown by your project listing, not an issue number. They are separate identifiers. For example, project 7 and issue 23 can appear together in a command, but 23 is not the project number:

$ 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. Read the complete command 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 difficult to notice in a busy workspace.

There is no dry-run flag in this command's installed help. If you need a final read-only check, inspect the project and item separately with the relevant gh project and gh issue or gh pr commands available in your installation. Do not replace a known item URL with 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 normal output format selected by the CLI:

$ 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 command's 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 that the account cannot see.

Checkpoint: do not blindly repeat a command after a network timeout. First inspect the project. A timeout does not prove that the server rejected the mutation.

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 returned by your installed release 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 and pull request URL is normally public metadata even when the project itself is restricted.

6. Verify or undo the addition

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

$ gh project item-list 7 --owner EXAMPLE_OWNER

Look for the issue or pull request title and confirm that it belongs to the expected project. If the item was added to the wrong project, record its item ID from the listing and use the matching gh project item-delete command after reading its help. Deleting a project item removes the association from the project, not the underlying issue or pull request. Check the target twice before deleting, because a mistaken item ID can remove a different association.