Create a Reviewable GitHub Issue with gh issue create

There is no dry run and no undo flag on gh issue create, so the review happens before the command, not after. This guide creates one GitHub issue from a checked title and body, optionally applies labels, assigns it, and records the URL GitHub CLI prints. Allow about ten minutes for a simple issue, including a final review. The examples use GitHub CLI 2.87.3, the version installed on this machine.

If the issue turns out wrong, keep its URL and use the repository's normal issue controls to close or edit it; do not create a second corrective issue without checking first.

1. Check the installed command and repository

Run these read-only checks from a shell. They need no elevated privileges and create nothing:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh repo view OWNER/REPOSITORY --json nameWithOwner
{"nameWithOwner":"OWNER/REPOSITORY"}

Replace OWNER/REPOSITORY with the repository that should receive the issue. Already in a checked-out repository: gh issue create normally uses that one. The explicit --repo OWNER/REPOSITORY form is safer in scripts and from an unrelated directory.

Checkpoint: stop if the repository name is wrong, or if gh repo view says you are not authenticated or cannot access it. Fix that before testing with a real issue.

2. Prepare the issue body

Put the proposed body in a file so it can be reviewed without shell quoting surprises. Use a new path in your working directory:

$ cat > /tmp/gh-issue-body.txt <<'EOF'
## What happened

The nightly import stops after the third input file.

## How to reproduce

1. Run the import with the attached sample data.
2. Observe the error in the job log.

## Expected result

All input files are processed, or the failed file is identified clearly.
EOF

The here-document is only an example of building a temporary body file. Review it before creating the issue: Markdown headings in the body reach GitHub as text for its issue renderer, not as shell commands.

Display the exact file and check its size:

$ sed -n '1,160p' /tmp/gh-issue-body.txt
$ test -s /tmp/gh-issue-body.txt && echo 'body is non-empty'
body is non-empty

3. Create the issue with explicit metadata

Review this command carefully before running it. It creates the issue immediately and normally prints the resulting web URL:

$ gh issue create \
    --repo OWNER/REPOSITORY \
    --title 'Import stops after the third input file' \
    --body-file /tmp/gh-issue-body.txt \
    --label bug \
    --label 'help wanted'
https://github.com/OWNER/REPOSITORY/issues/123

Use one --label per label. The command also accepts comma-separated values, but separate flags make spaces and the intended labels easier to see. Labels have to already exist in the repository; a missing one is an error, not an instruction to create it.

Do not run this with sudo. Elevated privileges grant no GitHub access and can leave authentication or configuration files owned by root instead of you.

Checkpoint: save the printed URL and open it in a browser. Confirm the title, rendered body, labels and repository before sharing it further.

4. Add an assignee, milestone or project when required

Add metadata in the same command once you know the exact names:

$ gh issue create \
    --repo OWNER/REPOSITORY \
    --title 'Document the import failure' \
    --body-file /tmp/gh-issue-body.txt \
    --assignee '@me' \
    --milestone '2026.10' \
    --project 'Roadmap'

@me assigns the issue to your own account. The special @copilot value works on this installed command but is not supported on GitHub Enterprise Server. A project assignment needs the GitHub project authorisation scope, and if it is missing, the manual points you to:

$ gh auth refresh -s project

That changes local authentication state and may open a browser. Complete it only when you trust the account and the host being authorised. Project optional: skip --project and create the issue without it.

5. Choose an interactive workflow when the body is not ready

With no title or body flags, gh issue create prompts for them. For an editor-based draft, use:

$ gh issue create --repo OWNER/REPOSITORY --editor

The first line of the editor buffer becomes the title, the rest becomes the body. --template NAME starts the body from a repository issue template; --web opens the browser instead, useful for inspecting repository templates or fields visually.

Both modes still end by creating an issue. Cancel at the prompt or close the browser page if the details are not ready. A failed create may leave recoverable input; the installed command provides --recover VALUE for that, so read the error it prints and use the supplied value exactly.

6. Diagnose a failed create

Check the exit status immediately, before another command replaces it:

$ gh issue create --repo OWNER/REPOSITORY --title 'Test title' --body 'Test body'
$ status=$?
$ printf 'gh issue create exit status: %s\n' "$status"
gh issue create exit status: 0

Only use a test title and body if you actually mean to create a test issue. Documented exit codes: 0 for success, 1 for an error, 2 for cancellation, 4 when authentication is required. Success means GitHub accepted the request; verify the printed URL and the issue page anyway.

Done means