Safely Unlink a GitHub Project from a Repository or Team

You will remove one association from a GitHub Project without deleting the project, repository or team. The examples use GitHub CLI 2.45.0, installed from the Ubuntu gh package on the machine checked for this guide. Allow about ten minutes, plus enough time to confirm the project number and target before making the change.

This is an authenticated, state-changing operation. You need GitHub CLI installed and logged in with permission to change the project association. No sudo is needed. The command can unlink either a repository or a team, and the target is selected by exactly one of --repo, --team, or the current repository fallback.

1. Check the installed command

Read the local help before preparing a command. This is an ordinary read-only check:

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

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

The installed command accepts a project number, an optional owner, and one repository or team target. It does not offer a dry-run flag in this version, so treat the final command as an immediate change.

Checkpoint: confirm the binary and package version you are about to use:

$ 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 changing a project. This avoids a common distraction: a valid login can still be the wrong personal account or GitHub Enterprise host.

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

Use the owner that contains the project. For a personal project, this is your login or the special value @me. For an organisation project, use the organisation login. The owner is not necessarily the repository owner when you are working across organisations.

If the status check reports the wrong host or account, stop. Change authentication deliberately with the normal gh auth workflow, then rerun the check. Do not try random owner values as a substitute for fixing the session.

3. Identify the project number and target

The positional number is the project number, not an issue number and not a repository ID. Use the project listing or the project URL to establish it, then write it down with 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

Do not put both --repo and --team in the same invocation. They describe different association types. If neither is supplied, gh project unlink uses the repository of the current directory, which is convenient only when you have first checked that directory.

4. Review the current repository context

If you intend to use 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)

Use explicit --owner and --repo when there is any doubt. A shell prompt opened in another clone can silently select a different repository. The fallback is also a poor fit for a team association, because it cannot select a team.

Checkpoint: before continuing, you should be able to say the project number, owner, and one exact target aloud. If any value is uncertain, stop and verify it in GitHub.

5. Unlink a repository

Unlink a project from a repository with --repo:

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

A successful command normally returns no result text and exits with status zero. Capture that status as a simple checkpoint:

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

Do not treat an empty terminal response as a preview. The association has been changed when the command exits successfully. If it fails, read the error before retrying. Authentication, permissions, an incorrect owner, a wrong project number and a repository that is not linked are different problems.

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 running this command.

7. Recover if you unlinked the wrong association

Unlinking is not a deletion of the project, but it is still a remote change. If you selected 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. If the original association had other permissions or project settings, check them in GitHub afterwards; this command restores the link, not unrelated configuration.