Pin and Unpin GitHub Issues Safely with gh

The same few issues matter every sprint and keep sliding off the first page: gh issue pin keeps one at the top of the list.

You get a tested undo command too, in about five minutes with the installed GitHub CLI 2.87.3, assuming you are already authenticated with an account allowed to manage the repository's issues.

Before you start

This is a repository change, although it does not edit the issue text, labels or code. Decide the exact repository and issue before running the pin command.

• You need: a working gh installation and an authenticated account allowed to manage the repository's issues.
• You do not need: elevated Linux privileges. sudo will not grant GitHub permission.

Use an issue number only when your current directory is a local checkout of the intended repository. Otherwise use the full issue URL or specify the repository with --repo. This avoids the common mistake of pinning an issue in a similarly named fork.

Checkpoint 1: confirm the target

Set a shell variable to the repository you intend to change. Replace the example with a real owner and repository name. The format is OWNER/REPO, or HOST/OWNER/REPO for another GitHub host.

$ REPO=OWNER/REPO
$ ISSUE=23
$ gh issue view "$ISSUE" --repo "$REPO" --json number,title,url,isPinned
{
  "isPinned": false,
  "number": 23,
  "title": "Example issue title",
  "url": "https://github.com/OWNER/REPO/issues/23"
}

Check the number, title and URL in the response. The title shown here is illustrative, because the real issue content belongs to your repository. If the command cannot find the issue, stop and correct the repository, number or authentication before trying to pin anything.

Checkpoint 2: pin the issue

Pin the checked issue using the repository-qualified form. The command accepts either an issue number or a URL. The --repo option is inherited from the parent issue command, and the manual documents it as the [HOST/]OWNER/REPO form.

$ gh issue pin "$ISSUE" --repo "$REPO"

A successful run normally returns to the shell without a result document. Treat the exit status as the first check, then query the issue rather than relying on the absence of an error message.

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ gh issue view "$ISSUE" --repo "$REPO" --json isPinned --jq '.isPinned'
true

If your shell has run another command first, the displayed exit status is no longer the pin command's status. In that case, run the pin command again and immediately print $?, or rely on the state query. Repeating a state-changing command without checking the target is an easy way to lose track of which repository you changed.

Pin by URL when you are not in a checkout

A full URL carries the repository and issue number in one value. It is useful in scripts or from an unrelated directory, but inspect the URL before pressing Enter because the command will act on the repository named there.

$ gh issue pin https://github.com/OWNER/REPO/issues/23
$ gh issue view https://github.com/OWNER/REPO/issues/23 --json isPinned --jq '.isPinned'
true

The local manpage lists both forms and does not document additional pin-specific flags. Do not add a guessed confirmation, force or output option. Use gh issue pin --help on the installed machine if you need to check the syntax after an upgrade.

Undo the change

Pinning is reversible, but unpinning changes the same repository state. First confirm that the issue is still the intended target, then use the matching unpin command. This is the recovery path if you selected the wrong issue or no longer want it highlighted.

$ gh issue unpin "$ISSUE" --repo "$REPO"
$ gh issue view "$ISSUE" --repo "$REPO" --json isPinned --jq '.isPinned'
false

You can also unpin by the full URL. If the command reports a permission or network error, do not assume the state changed. Run the read-only state query after connectivity or authentication is restored.

Common failures

• Wrong repository. An issue number is meaningful only within a repository. Always use --repo or a full URL when the current checkout is not unambiguous.
• Authentication or permission failure. Check the account and host with gh auth status. Changing Linux users or adding sudo does not change the GitHub account used by the CLI. Ask a repository administrator for the required access rather than trying alternate targets.
• Issue not found. Verify that the issue number is correct, that the repository is spelled exactly, and that your account can see the issue. A private repository may be invisible to an account without access.
• Verification says false. The issue is not pinned in the repository you queried. Recheck REPO, the issue URL and the account context before retrying.
• Scripting it? Quote variables and URLs, use set -u where it suits your script, and check each command's exit status. Do not accept an issue number from untrusted input without validating the repository and URL first.