Create and inspect GitHub issue branches with gh issue develop

You will use gh issue develop to see the branches linked to a GitHub issue, create a development branch and optionally check it out. Allow about ten minutes if you already know the issue number and repository. The command talks to GitHub, so you need a working gh login and permission to create branches in the target repository.

This guide describes the installed Ubuntu package, GitHub CLI 2.45.0. The local manual documents --base, --branch-repo, --checkout, --list and --name. Newer upstream manuals may show additional flags, such as --worktree; do not copy a flag into a script until gh issue develop --help on that machine lists it.

1. Check the client, login and repository

Start with read-only checks. Run these from a Git checkout, or use --repo OWNER/REPO explicitly so the command cannot act on an unintended repository.

$ gh --version
gh version 2.45.0
$ gh auth status
$ gh issue develop --help
$ git status --short

There should be no unexpected changes in the checkout before you use --checkout. A branch switch can interrupt uncommitted work. Authentication output varies, so the useful checkpoint is a successful status command and help text containing the flags you intend to use. No elevated privileges are required.

2. List branches already linked to an issue

Use the issue number as the final argument and add --list. This is the safest first operation because it only queries the issue's linked development branches.

$ gh issue develop --list 123
<linked branch information for issue 123>

The exact columns and wording are produced by GitHub CLI and can change. An empty list means that no linked development branch was returned for that issue; it does not identify a suitable branch name for you. If the issue is in another repository, make the repository part of the command:

$ gh issue develop --list --repo OWNER/REPO 123

Use either an issue number or an issue URL, as accepted by the command synopsis. Keep the repository and issue together when you are working across several clones.

3. Create a branch with an explicit name and base

Choose the branch name and the remote base branch deliberately. Supplying both makes the operation easier to review and avoids relying on an unstated default. The --base value is the remote branch from which the new development branch is created. When supplied, GitHub CLI also configures the new branch as the base branch for pull requests created with gh pr create.

$ gh issue develop 123 \
    --repo OWNER/REPO \
    --name issue-123-short-description \
    --base main
<new branch information>

Replace every uppercase placeholder. The branch name must follow the repository's branch policy. Do not put credentials, access tokens or issue text copied from an untrusted source into a shell command without checking its characters and quoting it.

Creating a branch changes remote repository state. It is not a local-only preview and there is no undo option in gh issue develop. Before running it, check that the issue and base are correct. If you created the wrong branch, inspect it in GitHub and remove it through your normal repository workflow only after confirming that nobody else is using it. Do not delete a shared branch as a quick fix.

Verify the link without creating a second branch:

$ gh issue develop --list --repo OWNER/REPO 123

4. Create and check out the branch

Add --checkout when you want GitHub CLI to switch the current checkout to the new branch after creation. Protect local work first. Commit it, stash it using your team's process, or stop and use a clean checkout.

$ git status --short
$ gh issue develop 123 \
    --repo OWNER/REPO \
    --name issue-123-short-description \
    --base main \
    --checkout
$ git branch --show-current
issue-123-short-description

The final line should be the name you requested. If the command created the branch but checkout failed, do not repeat the creation command with the same name. Inspect the local state with git branch --list and check the linked branches again with gh issue develop --list. Switch manually only after confirming that your working tree is safe.

There is no persistent configuration file to edit for this command. The issue link and remote branch are the state to verify; your local checkout state is separate.

5. Create the branch in a different repository

Use --repo for the repository containing the issue and --branch-repo for the repository where the branch should be created. This is useful for a coordinated fork workflow, but it increases the chance of targeting the wrong owner.

$ gh issue develop 123 \
    --repo upstream/project \
    --branch-repo YOUR-ACCOUNT/project \
    --name issue-123-short-description \
    --base main

Use the full repository name or URL accepted by your installed help output. Confirm both repositories and your write permission before running this state-changing command. Then list the issue using the issue repository and inspect the branch repository in its own context if the result is not as expected.

6. Diagnose failures without guessing

A failure before branch creation is usually safer than a partially understood success. First rerun the relevant read-only checks: gh auth status, gh issue develop --help, gh issue develop --list --repo OWNER/REPO 123 and git status --short. Check spelling, repository ownership, issue visibility and branch policy before changing anything.

If --name, --base or --branch-repo is rejected as an unknown flag, compare the installed help output with the command you copied. The installed 2.45.0 client is the authority for this machine. If the requested remote branch or repository is unavailable, correct the input rather than adding sudo; elevated privileges cannot grant GitHub permission or create a remote branch.