Unlink a GitHub Project with gh project unlink

Use gh project unlink to detach a GitHub Project from a repository or team without deleting any of the three. The examples use GitHub CLI 2.45.0 from the Ubuntu gh package. Allow about ten minutes, most of it spent confirming the project number and target before you change anything.

• State-changing and authenticated. You need gh installed and logged in with permission to change the project association. No sudo needed.
• One target only. Pick exactly one of --repo, --team, or the current repository fallback.

1. Check the installed command

Read the local help first. It is a read-only check:

$ gh project unlink --help
Unlink a project from a repository or a team

USAGE
  gh project unlink [<number>] [flags]

The command takes a project number, an optional owner, and one repository or team target. There is no dry-run flag in this version, so the final command is an immediate change.

$ command -v gh
/usr/bin/gh
$ gh --version | head -n 1
gh version 2.45.0

2. Confirm authentication and ownership

Check the account before you touch a project. A valid login can still be the wrong personal account or the wrong GitHub Enterprise host.

$ gh auth status
Logged in to github.com account YOUR_LOGIN

• Personal project. The owner is your login, or the special value @me.
• Organisation project. The owner is the organisation login.
• Cross-organisation work. The project owner is not necessarily the repository owner.

3. Identify the project number and target

The positional number is the project number. It is not an issue number and not a repository ID. Get it from the project listing or the project URL, then write it down next to the exact repository or team name.

For a repository association, prepare a command like this:

$ PROJECT_NUMBER=123
$ OWNER='YOUR_LOGIN'
$ REPOSITORY='YOUR_REPOSITORY'
$ printf 'project=%s owner=%s repo=%s\n' "$PROJECT_NUMBER" "$OWNER" "$REPOSITORY"
project=123 owner=YOUR_LOGIN repo=YOUR_REPOSITORY

For a team association, the target changes to a team name:

$ TEAM='YOUR_TEAM'
$ printf 'project=%s owner=%s team=%s\n' "$PROJECT_NUMBER" "$OWNER" "$TEAM"
project=123 owner=YOUR_LOGIN team=YOUR_TEAM

4. Review the current repository context

If you plan to rely on the current-directory default, inspect it immediately before unlinking:

$ git rev-parse --show-toplevel
/path/to/YOUR_REPOSITORY
$ git remote -v
origin  https://github.com/YOUR_LOGIN/YOUR_REPOSITORY.git (fetch)
origin  https://github.com/YOUR_LOGIN/YOUR_REPOSITORY.git (push)

When in doubt, pass --owner and --repo explicitly. A shell prompt sitting in another clone can silently pick a different repository. The fallback is also no use for a team association, because it cannot select a team.

5. Unlink a repository

Use --repo:

$ gh project unlink "$PROJECT_NUMBER" \
    --owner "$OWNER" \
    --repo "$REPOSITORY"

Success normally prints nothing and exits with status zero. Capture that status as your checkpoint:

$ printf 'exit status: %s\n' "$?"
exit status: 0

If it fails, read the error before retrying. These are all different problems:

• Authentication. The session is not valid for this host.
• Permissions. Your account cannot change the association.
• Wrong owner or project number. The project cannot be found.
• Not linked. The repository was never linked to the project.

6. Unlink a team

For an organisation project linked to a team, use --team instead:

$ gh project unlink "$PROJECT_NUMBER" \
    --owner "$OWNER" \
    --team "$TEAM"

Again, a zero exit status is the useful immediate verification:

$ printf 'exit status: %s\n' "$?"
exit status: 0

The owner identifies the project owner. It does not turn a personal project into an organisation project, and it does not grant access to a team. Confirm that your authenticated account can administer both the project and the association before you run this.

7. Relink if you removed the wrong association

Unlinking does not delete the project, but it is still a remote change. If you picked the wrong target, relink the same project with the matching gh project link command:

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

For a team, substitute --team "$TEAM". Verify the owner and target before relinking.