Link a GitHub Project to a Repository or Team with gh

A Project that nobody can find from the repository or team page might as well not exist, and gh project link fixes that from the shell. You will link an existing GitHub Project to either a repository or a team. The command changes project configuration on GitHub, so allow about five minutes for a single link and keep the project number, owner and target name to hand.

This guide describes the installed GitHub CLI 2.87.3, released on 23 February 2026. Check the version on your own machine before relying on exact diagnostics.

1. Check the installed command

Run the checks as your normal user. No root privileges are needed. The package metadata on this machine names an older Ubuntu package revision, but the executable itself reports 2.87.3. The executable and its help output are what determine the syntax you can use:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh project link --help
Link a project to a repository or a team

2. Confirm the project and target

A project number identifies the project within its owner account. The owner can be a user or an organisation. The target is either a repository or a team, selected with one flag. Before making the change, write down the exact values rather than relying on a similarly named project or team:

$ PROJECT_NUMBER='123'
$ OWNER='example-org'
$ REPOSITORY='example-repo'
$ TEAM='platform-team'

These assignments do not contact GitHub or change anything. Replace every example value.

• No URLs in --repo. Do not put a repository URL there unless the installed command explicitly documents URLs; the manpage describes the value simply as the repository to link.
• Check spelling hard. Treat names as case-sensitive enough to verify carefully, especially in an organisation with several teams.

3. Link the project to a repository

Use --owner and --repo for a repository target:

$ gh project link "$PROJECT_NUMBER" --owner "$OWNER" --repo "$REPOSITORY"

The manpage does not define a machine-readable success payload, so use the process exit status as the first verification point:

$ status=$?
$ printf 'gh project link exit status: %s\n' "$status"
gh project link exit status: 0

If the command returns a non-zero status, keep the error text, confirm the project number and owner, and check that your token can administer the project and see the repository.

4. Link the project to a team instead

If the project should be associated with an organisation team, use --team rather than --repo:

$ gh project link "$PROJECT_NUMBER" --owner "$OWNER" --team "$TEAM"
$ status=$?
$ printf 'gh project link exit status: %s\n' "$status"
gh project link exit status: 0

Use one target flag per invocation. The command's documented interface does not describe linking both a repository and a team in one call. If the same project needs both relationships, perform and verify each separately, recording which command created which association.

5. Use the current directory default carefully

When neither --repo nor --team is supplied, the documented example links the project to the repository of the current directory:

$ git remote -v
$ gh project link "$PROJECT_NUMBER" --owner "$OWNER"

This is convenient only when the working directory is definitely the intended repository. The command does not use the value of a shell variable called REPOSITORY, and changing directory changes the implicit target.

6. Check failures before retrying

Authentication, ownership, visibility and target spelling can all prevent the request. Treat a failed request as unverified: save the full diagnostic and inspect the status before deciding what to do next:

$ gh project link "$PROJECT_NUMBER" --owner "$OWNER" --repo "$REPOSITORY" 2>gh-project-link.error
$ status=$?
$ sed -n '1,12p' gh-project-link.error
$ printf 'exit status: %s\n' "$status"
exit status: 1

Remove the captured error after you have recorded the useful details and checked that it contains no sensitive token or account information:

$ rm -- gh-project-link.error

• Authentication is the problem. Use the supported gh auth workflow outside this guide, then retry the exact, reviewed command.
• Project number is wrong. Find the correct project through the GitHub interface or the appropriate read-only CLI command before attempting another link.

7. Undo a mistaken link

The supplied gh project link manual documents linking but does not document an unlink subcommand or an undo flag. There is therefore no verified inverse command to give here.