Create a git worktree from a Jira issue

worktree can derive branch names directly from Jira issues in your Jira workspace, on Jira Cloud or on Jira Data Center (see Jira Data Center).

Basic Usage

worktree branch --jira DEV-123
worktree branch --jira dev-123
worktree branch --jira https://company.atlassian.net/browse/DEV-123

The generated branch name is shown as the default in the prompt, so you can accept it or edit it before creation.

A pasted URL must be an issue’s /browse/<KEY> URL on your jira.host. Everything before /browse/ is compared with jira.host, ignoring case, so a site served under a context path (https://example.com/jira) matches only a URL that carries the same path. A URL on another base exits 2 with invalid_value, naming both, and that site is never contacted, so your credentials only go to jira.host. Pass the key, or check that the URL is from your Jira site.

How Branch Names Are Built

Read issue type and summary from the Jira API.
Sanitize the summary into a branch-safe slug, cut 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.
Optionally prepend a configured prefix based on issue type.

For example, a bug DEV-123 titled “Login redirect loops forever when the session cookie expires during checkout” becomes fix/DEV-123-login-redirect-loops-forever-when-the-session with branchPrefix.bugfix set to fix/.

Supported issue-type prefix mapping:

Feature, Story, and other non-bug/chore types -> branchPrefix.feature
Bug -> branchPrefix.bugfix
Task -> branchPrefix.chore

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

This built-in mapping applies only when no rules are set. If .worktree.yml has a jira.branchType list (or a shared top-level branchType list, which jira.branchType wins over), the rules decide the kind instead and the mapping above is not consulted: an issue no rule matches gets no prefix unless the list ends with - otherwise: <kind>. See Branch-type rules for the syntax, and for why to name fields and options by id. A shared list can name the issue type as Type, which Jira answers beside issuetype.

Assigning the issue

--assign assigns the Jira issue to the account behind jira.email (on Jira Cloud) or to the owner of the personal access token in jira.apiToken (on Jira Data Center) while the branch is created, and --no-assign skips it for one run. With neither, jira.autoAssign decides: true always assigns, false never does, and unset asks once and saves your answer. A non-interactive run (--json, --yes, CI) with the key unset assigns and saves nothing. This key is separate from github.autoAssign.

worktree branch --jira DEV-123 --assign
worktree branch --jira DEV-123 --no-assign
worktree config jira.autoAssign true

An issue someone else holds is never reassigned. Jira keeps one assignee, so writing yours would remove a colleague who may be working it. worktree warns with their name, leaves the issue as it is and creates the branch; --assign does not override this. An issue already assigned to you is reported as such and nothing is written. In the --json document, assigned is true when the issue is assigned now or was already yours, and false when someone else holds it.
The account needs the Browse Projects and Assign Issues permissions on the issue’s project. Without them, or when the issue is not found or Jira does not accept the account, worktree warns with what Jira said.
A failed assignment never stops the branch. The worktree is created either way, and assigned is false.
The assignment happens before the worktree is created, so a prompt is never buried behind creation output.

Moving the issue to in progress

--start moves the Jira issue to its in-progress status once the worktree exists, and --no-start skips it for that one run. Without either, jira.autoStart decides: true moves, false never does, and unset asks once in a terminal and saves the answer under that key. A non-interactive run with the key unset moves the issue and saves nothing, so pass --no-start or set the key to false if a script that passes --jira must not change an issue’s status. The full order and where it sits in a run are in the branch command.

worktree branch --jira DEV-123 --start
worktree branch --jira DEV-123 --no-start
worktree config jira.autoStart true

Jira workflows are per project and the statuses are renamed and translated freely, so nothing is matched by name. Jira groups every status into a category (To Do, In Progress, Done), and worktree goes by that. Up to three requests follow, each cut off after 15 seconds: the issue’s status, the transitions Jira offers from it, and the transition itself.

An issue in the To Do category moves through the transition that leads to an in-progress status. When the workflow offers several transitions that lead to the same status, the first is used.
An issue already in the In Progress category is not moved, and the document’s started is true. That costs one request.
An issue in the Done category, or in any other category, is left alone with a warning and started is false.
When the available transitions lead to more than one in-progress status, worktree does not guess which is “in progress” and writes nothing. The warning lists the statuses, started is false, and you move it in Jira.
When Jira offers no in-progress transition, the warning says so and started is false. Jira answers with an empty list both when the workflow has no such transition and when the account lacks the permission, so the warning names both causes.
A transition whose screen has a required field is refused by Jira. The warning names the transition and says it may need a field set in Jira, started is false and nothing changes.
Only the status changes: no assignee, comment or field is written. --assign and --start are separate requests, and one failing does not affect the other.
The account needs the Browse Projects and Transition Issues permissions on the issue’s project. A failed move never stops the branch: the worktree is created either way, the warning appears in warnings, and the exit code is unaffected.
The move happens after the worktree exists, before the env files, the install and the opener, and never when reopening an existing worktree. A dry run ignores --start and asks nothing.

Authentication Resolution

Authentication is resolved in this order:

Existing jira.host, jira.email, and jira.apiToken in git config, with jira.deployment (default cloud) deciding which are needed: on datacenter, jira.email is neither required nor read and jira.apiToken holds a personal access token. jira.host is read from git config, else from the team’s .worktree.yml, with no prompt; a file’s host receives everyone’s credentials, see Project Configuration.
Interactive prompts for missing values, then save to local git config.

Suggested Setup

worktree config jira.host https://your-domain.atlassian.net
worktree config jira.email your-email@example.com
worktree config jira.apiToken <api-token>
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 jira.host,jira.email,jira.apiToken,branchPrefix.feature,branchPrefix.bugfix,branchPrefix.chore

An empty answer to the token prompt keeps the token already stored rather than clearing it.

Jira Data Center

Set the deployment once, beside the host. Jira Server (end of support 2024-02-15) is the same API, so it uses datacenter too:

worktree config jira.deployment datacenter
worktree config jira.host https://jira.example.com
worktree config jira.apiToken <personal-access-token>

jira.deployment is a team key (it can sit under jira: in .worktree.yml), takes exactly cloud or datacenter, and is never asked by worktree config. Unset means cloud, which is how every existing install keeps working. It is configured, not detected, because a Cloud site can have a custom domain.

A personal access token (PAT), sent as a Bearer token. On Data Center worktree sends Authorization: Bearer <jira.apiToken>; there is no email and no Basic authentication, and a leftover jira.email is ignored. PATs need Jira 8.14 or later (Jira Service Management 4.15 or later); older versions are not supported. Create one under your avatar, Profile, Personal access tokens, Create token (Using Personal Access Tokens).
REST API version 2. Data Center is called at /rest/api/2/...; Jira Cloud stays on /rest/api/3/....
A context path is allowed. worktree config jira.host https://example.com/jira requests https://example.com/jira/rest/api/2/..., and a pasted URL must carry the same path.
Always https. A scheme in jira.host is dropped and every request goes over https, so the token is never sent in clear.
A private certificate authority. If the site’s certificate is signed by an authority Node does not know, requests fail with a TLS code such as UNABLE_TO_VERIFY_LEAF_SIGNATURE, and the error says so. Start worktree with Node’s NODE_EXTRA_CA_CERTS pointing at a file of the extra certificates in PEM format. Node reads it only when the process starts, so set it in the shell before running worktree, not from inside it (Node.js CLI: NODE_EXTRA_CA_CERTS=file).
Terminal window
```
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-ca.pem worktree branch --jira DEV-123
```
Issue keys may contain an underscore. A Data Center admin can allow it in the project key format, so MY_EXAMPLE_PROJECT-15 is accepted on datacenter and refused on cloud, before any request. The key still starts with a letter.
An unreachable site is named by host and error code only, for example Jira: could not reach jira.example.com (ENOTFOUND).. No header text is ever shown. This applies to Jira Cloud as well.
A request that could not be made is a config problem, not a network one. Node refuses some requests before connecting: a jira.host it cannot parse, one carrying user:password@, a blocked port, or (on datacenter) a token with characters a header cannot carry. Those read Jira: the request to jira.example.com could not be made (TypeError). Check jira.host and jira.apiToken in your config., naming only jira.host on cloud.
A 401 names the likely fix. On cloud with a host outside atlassian.net, the error suggests worktree config jira.deployment datacenter; on datacenter with an atlassian.net host it says Jira Cloud uses cloud.

Getting a Jira API Token

On Jira Cloud:

Visit Atlassian Account Settings
Click “Create API token”
Copy the generated token and use it with worktree config jira.apiToken

On Jira Data Center (8.14 or later), create a personal access token instead, as in Using Personal Access Tokens:

In Jira, select your avatar at the top right, then select Profile.
Select Personal access tokens in the left-hand menu.
Select Create token, give it a name and, if you like, an expiry.
Select Create, copy the token and use it with worktree config jira.apiToken. Jira does not show it again once you select Close.

worktree config shows these steps in place of the Cloud ones when jira.deployment is datacenter. See Jira Data Center.

The token is stored locally in git config and never sent anywhere except to your Jira instance.