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

Checkpoint: the command must exist and the help text must show --owner, --repo and --team. If gh is missing, stop and install or repair GitHub CLI through your normal system-management process.

Warning: do not use sudo to compensate for an authentication or project-permission error.

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

Warning: do not run this step and the team step merely to see which works. Linking is a state change, and repeating it can obscure which target you intended.

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.

Tip: check git remote -v first, then prefer an explicit --repo in a script or a procedure copied by someone else.

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.

Warning: do not paste an access token into a command line or error report.

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.

Recovery: if you linked the wrong target, stop repeating the command and remove or correct the association through the GitHub project interface or another documented administrative workflow after confirming the project and target. Record the old and intended relationships before changing anything else.

Warning: do not delete the project as a workaround. Deleting a project is a separate, destructive action and is not required to correct a link.

Done means

Syntax matches. gh --version and gh project link --help agree with the syntax you used.
Names checked. You verified the project number, owner and exact repository or team name.
One target per call. You used exactly one target flag, or deliberately verified separate links.
Exit status 0. The command succeeded and you kept the intended target in your notes.
Default understood. Omitting target flags uses the current directory's repository.
Fix path ready. You have a reviewed administrative route for correcting a mistaken link.