Jira の課題キーから Git ブランチ名を自動生成する

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

Jira の課題キーを含むブランチ名の形

Jira の課題キーを含むブランチとは、名前に課題キーを埋め込んだ Git ブランチのことです。たとえば feature/DEV-482-add-oauth-login のような形です。重要なのは大文字のキー（DEV-482）の部分です。リポジトリを Jira に接続しておくと、Jira はブランチ名、コミットメッセージ、プルリクエストからこのパターンを探し、一致したものをすべて課題の開発パネルにひも付けます。ボード上のカードから、それを完了させた実際のコードまで、誰もリンクを手で貼らずに追跡できるようになります。

多くのチームが落ち着く慣習は、3 つの要素からできています。

機械的な作業は、「DEV-482」とその課題の要約から、毎回一貫した正しいブランチ名を作ることです。atlassian-cli による 1 行の照会は、まさにこの手間をなくします。ブラウザーを開いて要約をコピーし、小文字にして空白を置き換える代わりに、キーを渡すだけで残りはツールが行います。

キーをどこに置くべきか、その理由

キーはブランチ名とコミットメッセージのどちらに入れるべきか、とよく聞かれます。短い答えはこうです。Jira は 3 つの場所すべてから読み取り、それぞれで少しずつ違う情報が見えるようになります。

キーをブランチ名に入れるのが最も効果の大きい選択です。ほかのすべてをそこから導き出せる唯一の場所だからです。ブランチがキーを持っていれば、Git フックがすべてのコミットにキーを写してくれるので、最初のチェックアウト以降 DEV-482 と打つことは二度とありません。この記事の残りは、そのパターンを組み立てていきます。

課題キーからブランチ名を生成する

まずは、課題キーを受け取り、要約を取得してスラッグ化し、ブランチを作成するシェル関数から始めます。~/.zshrc か ~/.bashrc に入れてください。

# jira-branch DEV-482            -> feature/DEV-482-add-oauth-login
# jira-branch DEV-482 bugfix     -> bugfix/DEV-482-add-oauth-login
jira-branch() {
  local key="$1"
  local type="${2:-feature}"

  # Pull the summary straight from Jira
  local summary
  summary=$(atlassian-cli jira issue get "$key" --format json | jq -r '.fields.summary')

  # Lowercase, replace non-alphanumerics with hyphens, trim, cap length
  local slug
  slug=$(printf '%s' "$summary" \
    | tr '[:upper:]' '[:lower:]' \
    | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g' \
    | cut -c1-40 | sed -E 's/-+$//')

  git checkout -b "${type}/${key}-${slug}"
}

これで、正しい名前のブランチ作成はコマンド 1 つになります。課題キーの形式は常に一貫し、スラッグは実際の要約と必ず一致し、ブランチ名のタイプミスはなくなります。

# Issue DEV-482 summary: "Add OAuth login flow"
$ jira-branch DEV-482
Switched to a new branch 'feature/DEV-482-add-oauth-login-flow'

この照会はコマンドリファレンスに記載されている標準の --format json 出力を使っているため、スラッグを短くする、区切り文字を変える、ユーザー名を前に付けるなど、チームの好みに合わせてブランチ名を整形できます。唯一守るべき規則は、Jira が検出できるようにキーを大文字のままにしておくことです。

ブランチ作成とカードの移動を 1 手で行う

ブランチを切る瞬間は、たいてい作業が「In Progress」になる瞬間でもあります。遷移を同じ関数に組み込んで、Git とボードがずれないようにしましょう。

jira-start() {
  jira-branch "$1" "${2:-feature}"
  # Advance the issue on the board (transition name must exist in the workflow)
  atlassian-cli jira issue transition "$1" --transition "In Progress"
}

コマンド 1 つ（jira-start DEV-482）で、ブランチの作成と Jira の更新が完了します。ワークフローによって遷移名が異なる場合は、まず atlassian-cli jira issue get DEV-482 で有効な遷移先を確認し、文字列を調整してください。

Git フックで全コミットに自動でキーを付ける

コミットを Jira の課題に表示させるには、各コミットメッセージにキーが含まれている必要があります。毎回手で打つのは、忙しいときにこそ忘れがちな作業です。prepare-commit-msg フックを使えば、ブランチ名からキーを読み取って先頭に付けてくれます。

リポジトリに .git/hooks/prepare-commit-msg を作成し、実行権限を付けます。

#!/usr/bin/env bash
# .git/hooks/prepare-commit-msg
# Prepend the Jira issue key from the branch name to every commit message.
set -euo pipefail

msg_file="$1"
branch=$(git rev-parse --abbrev-ref HEAD)

# Match keys like DEV-482, ABC-1, PLATFORM-99
key=$(printf '%s' "$branch" | grep -oE '[A-Z][A-Z0-9]+-[0-9]+' | head -1 || true)

# Only add it if we found a key and it is not already in the message
if [ -n "$key" ] && ! grep -q "$key" "$msg_file"; then
  printf '%s %s' "$key" "$(cat "$msg_file")" > "$msg_file.tmp"
  mv "$msg_file.tmp" "$msg_file"
fi

これ以降、feature/DEV-482-add-oauth-login でコミットすると、キーに触れることなく DEV-482 Fix token refresh race のようなメッセージになります。すべてのコミットが課題に載り、キーがあるので Smart Commit のアクション（たとえば末尾の #time 2h や #comment）も機能します。

ブランチにキーがない場合（main や検証用のブランチにいるときなど）、フックは何にも一致せずメッセージをそのまま残すため、どこで有効にしても安全です。

どのブランチからでも課題を調べる

この関係は双方向に働きます。ブランチがキーを持つようになれば、Git のどこにいても、対象の課題を探し回らずにそこへ戻れます。現在のブランチからキーを取り出し、jira issue get に渡します。

# Show the issue behind the branch you are standing on
jira-here() {
  local key
  key=$(git rev-parse --abbrev-ref HEAD | grep -oE '[A-Z][A-Z0-9]+-[0-9]+' | head -1)
  [ -z "$key" ] && { echo "No Jira key in branch name"; return 1; }
  atlassian-cli jira issue get "$key"
}

jira-here を実行すると、現在のブランチに対応する課題の要約、ステータス、担当者がターミナルに表示されます。コードレビュー中や、1 週間ぶりにブランチへ戻って何のためのものか思い出せないときに便利です。

同じ取り出し方が、軽量なガードにも使えます。pre-push フックを使えば、プッシュ前にキーが実在する課題を指しているかを確認でき、打ち間違えたキーや、削除済みの課題に対応するブランチを早い段階で見つけられます。

#!/usr/bin/env bash
# .git/hooks/pre-push  -- warn if the branch key is not a real Jira issue
branch=$(git rev-parse --abbrev-ref HEAD)
key=$(printf '%s' "$branch" | grep -oE '[A-Z][A-Z0-9]+-[0-9]+' | head -1 || true)

if [ -n "$key" ]; then
  if ! atlassian-cli jira issue get "$key" --format json >/dev/null 2>&1; then
    echo "Warning: $key did not resolve to a Jira issue"
  fi
fi
exit 0

このチェックは助言的なもので（終了コード 0 を返すのでプッシュを止めません）、間違いを早い段階で表に出します。Jira に対してより高度なチェックをスクリプト化したい場合、生の JSON 出力は コマンドラインからの Jira API ガイド全体で使われているものと同じ形なので、2 つのワークフローはきれいに組み合わせられます。

atlassian-cli と acli の違い

atlassian-cli は、コミュニティによる独立したオープンソースプロジェクトです。Atlassian が提供する公式 CLI（acli）ではなく、Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。ベンダーによる一次サポートが必要であれば公式の acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management を横断し、上記のようなシェル関数や Git フックにそのまま組み込める一貫した --format json 出力を備えた単一の無料 Rust バイナリが欲しい場合は、atlassian-cli を使ってください。

このワークフローで実際に効いてくるのは、製品をまたいで統一された JSON です。ここで jq -r '.fields.summary' に渡している --format json は、プルリクエストやレビューの自動化でもそのまま使えます。ブランチをそのまま PR に進める場合は、Bitbucket の PR レビュー自動化ガイドがこの記事の続きにあたり、同じキーでレビューを課題にひも付けます。

よくある質問

関連リソース