GitHub Issue Integration

worktree can derive branch names directly from GitHub issues in the current repository, and assign the issue to you at the same time.

Basic Usage

worktree branch --github 42
worktree branch --github "#42"
worktree branch --github 42 --assign

The generated branch name is shown as the default in the prompt, so you can accept it or edit it before creation. A non-interactive run takes it without asking.

How Branch Names Are Built

1. Read issue number and title from the GitHub API.
2. Sanitize the title into a branch-safe slug: lowercase letters, digits and dashes only, so a title can never add a / or .. to the name.
3. Cut the slug to at most 48 characters at the last dash, so it ends on a whole word. A single word longer than 48 characters is cut at 48.
4. Optionally prepend a configured prefix based on issue type, giving <prefix><number>-<slug>.

For example, an issue 42 titled “Add a dark mode toggle to the settings page so that users can switch themes at runtime” becomes 42-add-a-dark-mode-toggle-to-the-settings-page-so. The name is the same whether or not you are prompted.

Supported issue-type prefix mapping:

• Feature -> branchPrefix.feature
• Bug -> branchPrefix.bugfix
• Task -> branchPrefix.chore

If a prefix key is not configured, no prefix is applied.

Authentication Resolution

Authentication is resolved in this order:

1. Existing github.token in local git config.
2. gh auth token from GitHub CLI.
3. Interactive prompt for a token, then save to local git config. A non-interactive run has no prompt: it exits 2 naming worktree config github.token <token> or gh auth login, and never prints a token.

Reading an issue and assigning one need different amounts of access. A public repository answers an unauthenticated read, which is why --github has never required a token there. Assigning always requires a token, and that token needs push access to the repository — so the first time you assign on such a repository you may be asked for one, unless the resolution order above already supplies it.

Assigning the Issue

Creating the branch is the moment you have demonstrably started work, so worktree can say so on the issue for you.

The decision is made in this order:

1. --assign assigns it to the authenticated user; --no-assign skips it for that run.
2. github.autoAssign: true always, false never. An explicit false is respected in every mode.
3. A non-interactive run assigns. The default is not saved, so one unattended run does not settle the key.
4. Otherwise you are asked once, and your answer is saved to github.autoAssign.

To change your mind later:

worktree config github.autoAssign true

worktree confirms the assignment against the API response rather than assuming it worked, and reports a warning if the issue comes back without you on it. A failed assignment never stops the branch — the worktree is created regardless.

Suggested Setup

worktree config github.token <token>
worktree config github.autoAssign true
worktree config branchPrefix.feature feature/
worktree config branchPrefix.bugfix fix/
worktree config branchPrefix.chore chore/

You can also configure only missing values:

worktree config --missing --names github.token,github.autoAssign,branchPrefix.feature,branchPrefix.bugfix,branchPrefix.chore