Lock a GitHub Issue Conversation with gh issue lock

A heated thread keeps getting replies after the actual problem was fixed: gh issue lock shuts down further conversation, with a reason attached.

The command changes remote issue state, so allow two or three minutes to check the repository, issue number and permissions before running it.

Before you start

Install GitHub CLI and sign in to the GitHub host that owns the repository. The installed command checked for this guide is GitHub CLI 2.87.3, dated 2026-02-23. The local gh-issue-lock(1) manual documents the same interface as the current upstream manual: an issue number or URL, an optional reason, and an optional repository selector.

You need: the repository name, the issue number, and an authenticated account allowed to manage the issue conversation. That is an account or GitHub permission requirement, not a Linux root one.

Check the command without changing anything:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh issue lock --help

The help output should show gh issue lock {<number> | <url>} [flags] and the --reason option.

Checkpoint: identify the exact issue

First view the issue you intend to moderate. Substitute a real repository and issue number for the placeholders. This is a read-only check:

$ gh issue view 123 --repo OWNER/REPO
Issue title appears here
...

The --repo option is inherited from the parent command and accepts [HOST/]OWNER/REPO. You can instead pass the issue URL directly, which is useful when working across GitHub hosts:

$ gh issue view https://github.com/OWNER/REPO/issues/123

Do not rely on a copied number without checking its repository. Issue 123 in one repository is unrelated to issue 123 in another.

1. Choose a documented lock reason

The local manual accepts four reason values: off_topic, resolved, spam and too_heated. The reason is optional, but supplying one leaves a clearer moderation record and prevents a later operator from having to infer your decision.

Use the value that describes the conversation, not one that describes your personal reaction. Use resolved when the issue has reached its end, or off_topic when further replies no longer concern it.

2. Lock the conversation

Warning: This sends a state-changing request to GitHub. Locking prevents further conversation on the issue until it is reversed. Confirm the repository and number immediately before running the command.

$ gh issue lock 123 --repo OWNER/REPO --reason resolved

A successful command normally produces no useful output and returns exit status zero. Check that status in a shell when you need an explicit checkpoint:

$ gh issue lock 123 --repo OWNER/REPO --reason resolved
$ printf 'lock request exit status: %s\n' "$?"
lock request exit status: 0

The command also accepts the short form:

$ gh issue lock -R OWNER/REPO -r off_topic 123

Keep the issue number as a separate argument. Quoting the entire command or adding prose after the number does not create a moderation note; it only risks passing an invalid argument.

3. Verify the remote state

The local gh issue view JSON fields do not expose a lock field in the installed CLI help. Query the GitHub REST API instead. This read-only request prints the server's current boolean state:

$ gh api repos/OWNER/REPO/issues/123 --jq '.locked'
true

Use the URL form when the repository is on another GitHub host, or set the host explicitly through the normal GitHub CLI configuration. If the result is false, the issue is not locked from the viewpoint of that API request. An authentication error, a repository typo or a non-zero exit status is not proof that the lock failed; fix the reported problem and query again.

For an audit-friendly check that includes the issue title as well as the state, request both fields:

$ gh api repos/OWNER/REPO/issues/123 --jq '(.title + " | locked=" + (.locked | tostring))'
Issue title appears here | locked=true

Undo the lock

Locking is reversible. If the issue needs more discussion, reverse it with the sibling command below. This is another state-changing request, so verify the target first:

$ gh issue view 123 --repo OWNER/REPO
Issue title appears here
...
$ gh issue unlock 123 --repo OWNER/REPO
$ gh api repos/OWNER/REPO/issues/123 --jq '.locked'
false

gh issue unlock has no reason option. Reversing the lock permits conversation again; it does not restore or edit comments and it does not reopen an issue that was closed separately.

Common failure points

Missing authentication: GitHub CLI may report that authentication is required. Sign in for the correct host, then repeat the read-only gh issue view check before attempting the lock.
Wrong repository: a command run from a local checkout can use its repository context, which may not be the repository you meant to moderate. Keep --repo OWNER/REPO in operational scripts and copy-paste examples when there is any ambiguity.
Invalid reason: use one of the four documented values exactly. The underscores in off_topic and too_heated are part of the value.
Confusing a closed issue with a locked issue: closing and locking are separate states. Check .locked through gh api; do not infer it from the issue's open or closed state.
API verification fails: the lock request and the verification request can fail for different reasons. Preserve the error text, check the host and repository, and retry the read-only query before sending another state-changing request.

Done means

The issue title and repository were checked before the change.
The lock command returned exit status zero.
gh api ... --jq '.locked' printed true.
The reason was one of off_topic, resolved, spam or too_heated.
You know that gh issue unlock reverses the lock without reopening a closed issue.