git-jira-branch - Manage branches for your Jira tickets

Creates feature branches based on your Jira tickets type and description.

$ git jira-branch create MYAPP-1234
> Successfully created branch: 'feat/MYAPP-1234-sluggified-description-used-as-branchname'

• Usage
  • Pick a Jira ticket interactively
  • Create a new branch from your current HEAD
  • Create a new branch based on some other revision
  • Reset an already existing branch
  • Open tickets in your browser
  • Show ticket info on your terminal
  • Attach GitHub PR links to the current branch ticket
  • List branches associated with jira tickets
  • wizard mode
• Setup
  • Install
• Configuration
  • For Jira Cloud
  • For Jira Data Center
  • Setup shell completions
• Development
  • Run E2E tests against local sources
  • Write release notes with Changesets
• Contributors
• Technologies used
• License

Usage

Since this command starts with git- all commands can be run via git-jira-branch or as a git subcommand with git jira-branch.

Due to a limitation in the awesome cli library used, all options must be passed before the jira ticket key argument.

Pick a Jira ticket interactively

For create, switch, and delete, the Jira ticket key is optional. If you leave it out, git-jira-branch opens an interactive ticket picker that searches Jira as you type and includes matching local branches.

git-jira-branch create
git-jira-branch switch
git-jira-branch delete

The picker lets you search with a full key like MYAPP-1234 or, when JIRA_KEY_PREFIX is configured, just the issue number. It also makes branch state visible: create shows whether a branch already exists, while switch and delete only allow tickets that have an associated local branch.

Create a new branch from your current HEAD

Using the default JIRA_KEY_PREFIX

git-jira-branch create 1324

Or fully specified:

git-jira-branch create MYAPP-1234

Create a new branch based on some other revision

To create a new branch based on your master branch:

git-jira-branch create -b master MYAPP-1234

Reset an already existing branch

Pass the -r|--reset flag to reset an already existing branch to the current HEAD or the specified base revision (with -b)

git-jira-branch create -r MYAPP-1234

Switch to an already existing branch that is associated with a Jira ticket

To switch to an already existing branch that is associated with a Jira ticket you can use the switch command.

git-jira-branch switch MYAPP-1234

Open tickets in your browser

1. For the current branch:

   $ git jira-branch open
   > Opening ticket url 'https://gcjb.atlassian.net/browse/GCJB-164' in your default browser...

2. For a given ticket:

   $ git jira-branch open GCJB-1234
   > Opening ticket url 'https://gcjb.atlassian.net/browse/GCJB-1234' in your default browser...

Show ticket info on your terminal

The info command shows the information for ticket nicely rendered for consumtpion in the terminal.

By default info is show for the ticket associated with the current branch. Alternatively a ticket key can be passed as an argument to show info for that ticket.

$ git jira-branch info

Will create output like this:

GCJB-1 - Ticket summary
Task | Status: To Do | Creator: Alexander Pankoff | Assignee: Alexander Pankoff

Long lines in the description of the ticket are wrapped to fit a line width of
80 characters to make it easier to read.

Attach GitHub PR links to the current branch ticket

The link-pr command resolves the Jira ticket from the current branch, or uses an explicit Jira key if provided, detects the GitHub repository from your git remotes, finds pull requests in that repository whose head branch contains the Jira key, and adds missing Jira remote links for those pull requests.

It prefers a GitHub upstream remote, then origin, and otherwise uses the first GitHub remote. You can override that with --remote <name> or bypass remote detection entirely with --repo <owner/repo>. Supported remote formats include SSH (git@github.com:..., ssh://git@github.com/...) and HTTPS (https://github.com/...).

By default, link-pr scans the newest 500 pull requests. Override that with --scan-limit or LINK_PR_SCAN_LIMIT, or use all to scan full history. The search currently scans pull requests across all GitHub PR states and matches on the head branch name.

$ git jira-branch link-pr
> Linked 1, skipped 1.
> linked #42 https://github.com/my-org/my-repo/pull/42
> skipped #40 https://github.com/my-org/my-repo/pull/40

$ git jira-branch link-pr FOOX-1234

Examples:

git-jira-branch link-pr --scan-limit 1000 FOOX-1234
git-jira-branch link-pr --scan-limit all FOOX-1234
git-jira-branch link-pr --remote upstream FOOX-1234
git-jira-branch link-pr --repo my-org/my-repo FOOX-1234
git-jira-branch link-pr --provider github FOOX-1234

List branches associated with jira tickets

$ git jira-branch list
> * feat/GCJB-1-e2e-test-ticket-with-a-fancy-summary
>   feat/GCJB-2-another-ticket-that-looks-like-its-associated-with-a-jira-ticket

wizard mode

Use the --wizard option to enter wizard mode. This will prompt you for the Jira ticket key and additional options and build the appropriate command line for you.

git-jira-branch --wizard

Setup

Install

The cli can be installed from npm. It assumes you have git installed on your system and the git command to be available on your $PATH.

npm i -g git-jira-branch

Configuration

For Jira Cloud

1. Create a Jira API Token See Jira Docs
2. Add the created API Token, your login email, the base url of your Jira instance and optionally a default Jira key prefix to your environment. For example in your .bashrc or .zshrc:

   export JIRA_USER_EMAIL="YOUR_JIRA_LOGIN_EMAIL"
   export JIRA_API_TOKEN="YOUR_API_TOKEN"
   export JIRA_API_URL="https://jira.mycompany.com"
   export JIRA_KEY_PREFIX="MYAPP"

For Jira Data Center

Note: this project is tested against a Jira Cloud instance. Jira Data Center support is best effort: it is not covered by the E2E test suite and has not been tested by the author.

1. Create a Jira PAT (Personal Access Token) See Jira Docs
2. Add the created Jira PAT, the base url of your Jira instance and optionally a default Jira key prefix to your environment. For example in your .bashrc or .zshrc:

   export JIRA_PAT="YOUR_PERSONAL_ACCESS_TOKEN"
   export JIRA_API_URL="https://jira.mycompany.com"
   export JIRA_KEY_PREFIX="MYAPP"

For link-pr only, set one GitHub token:

export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
# or
export GH_TOKEN="YOUR_GITHUB_TOKEN"

If both are present, GITHUB_TOKEN takes precedence.

Optional default scan window for link-pr:

export LINK_PR_SCAN_LIMIT="500"

LINK_PR_SCAN_LIMIT must be a positive integer. It only affects link-pr and can be overridden per invocation with --scan-limit.

Setup shell completions

The cli can generate shell completion scripts for bash,zsh and fish. To generate and print the script for your shell run:

git-jira-branch --completions (bash|zsh|fish)

To install the completions for your shell, run the above command and pipe the output to a file and source it in your shell config.

E.g. for bash:

git-jira-branch --completions bash > ~/.git-jira-branch-bash-completions
echo "source \$HOME/.git-jira-branch-bash-completions" >> ~/.bashrc
source ~/.bashrc

Development

Run E2E tests against local sources

Running pnpm e2e-test locally type-checks, rebuilds the CLI, and then executes the freshly built binary (node dist/main.js) against the fixtures, so no extra setup is required.

In CI you can call pnpm e2e-test:ci, which defaults to GIT_JB_BIN=git-jira-branch unless you override the variable before invoking the command. This lets you choose whether the suite exercises the published package or a specific binary path.

Write release notes with Changesets

Commits should be atomic and have clear, descriptive messages; no type or scope prefix is required. Versions and changelogs are controlled explicitly with Changesets, not inferred from commit messages. Pull requests are rebase-merged so their individual commits remain in the project history.

Every pull request that should change the published package needs a changeset:

pnpm changeset

Choose patch, minor, or major, then write a concise note for end users. The note is copied into CHANGELOG.md and the GitHub release, so describe the user-visible outcome rather than the implementation or commit mechanics. Commit the generated .changeset/*.md file alongside the change. Documentation, tests, CI changes, and internal refactors that do not affect the published package do not need a changeset.

After changesets reach master, the release workflow collects them in the Release package updates pull request. Merging that pull request publishes the new version to npm and creates the corresponding GitHub release automatically.

Contributors

• Alexander Pankoff (@ccntrq)
• Jakob Friedrich (@jakobtfr)
• Taylor Falk (@taytayp @tfalkarkea)

Technologies used

This project was started as an excuse to explore the Effect ecosystem and was written with only @effect/* packages as it's runtime dependencies. It uses:

Package	Usage
effect	The core effect system and runtime.
@effect/cli	Command line handling and option parsing. The wizard mode and --completions option are automatically provided by this lib.
@effect/platform	For its http client.
@effect/platform-node	For its shell command executor.

It uses the Jira API to fetch the details for a ticket and calls out directly to git for branch creation.

Tests were written using vitest. The testsuite can be run using pnpm test.

License

The code in this repository is licensed under the MIT License. Please note that the MIT License applies only to the code in this repository and not to any other assets, especially not the Logo.