GitHub Actions と CI/CD で Jira CLI を使う

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

GitHub Actions で Jira コマンドを動かす理由

Jira と GitHub Actions を組み合わせると、コードが流れていくのに合わせてパイプラインが Jira を更新できます。プルリクエストが開いたら課題を「In Review」へ移し、本番へのデプロイが成功したら「Deployed」へ遷移させ、その課題を該当のビルドにひも付けるコメントを残す、といったことです。これをランナー上で現実的に行える道具がコマンドラインクライアントで、atlassian-cli は 1 ステップでインストールでき、スクリプトから呼び出せる自己完結した単一バイナリです。

これを CI でやると、誰もが忘れる手作業、つまりリリース後にボード上のカードを動かす作業がなくなります。人が Jira を現実に合わせるのではなく、実際にデプロイを行ったパイプライン自身が何が起きたかを記録します。ステータスの変更は本物のイベント（ビルドの成功、デプロイの成功）に結び付いているので、ボードは誰かがスタンドアップで語る推測ではなく、作業の実際の状態を映します。

ランナーに CLI をインストールする

GitHub がホストする既定の ubuntu-latest ランナーには Rust のツールチェーンが最初から入っているので、いちばん簡単なインストールは 1 行で済みます。Jira コマンドより前のステップとして追加します。

# Simplest: build and install from crates.io
- name: Install atlassian-cli
  run: cargo install atlassian-cli

cargo install はソースからコンパイルするため、ジョブに 1 分か 2 分ほど加わります。パイプラインを速くしたい場合は、同じくらい妥当な選択肢が 2 つあります。

• ビルド済みバイナリ。 GitHub のリリースページからランナーのプラットフォーム向けの成果物をダウンロードし、展開して PATH に追加します。コンパイルの工程を丸ごと避けられます。
• Homebrew。 macOS のランナー（および Homebrew が使える Linux ランナー）では brew install omar16100/atlassian-cli/atlassian-cli を実行します。

どの経路を選んでも結果は同じで、あとのステップから呼び出せる atlassian-cli のバイナリが PATH 上に置かれます。バージョン確認で解決できているか確かめておきます。

- name: Verify install
  run: atlassian-cli --version

GitHub のシークレットで認証する

API トークンをワークフローファイルに書いてはいけません。3 つの値をリポジトリシークレットとして保存します（Settings → Secrets and variables → Actions）。サイトの URL、アカウントのメールアドレス、そして API トークンです。API トークンとパーソナルアクセストークンの違いは Atlassian の API トークンと PAT の違いで扱っています。

ワークフローの中では、これらのシークレットをステップ内の環境変数として公開し、auth login に渡します。変数を引用符で囲んでおけば、値に特殊文字が含まれていても安全です。

- name: Authenticate to Jira
  env:
    JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
    JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
    JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
  run: |
    atlassian-cli auth login \
      --profile ci \
      --base-url "$JIRA_BASE_URL" \
      --email "$JIRA_EMAIL" \
      --token "$JIRA_API_TOKEN" \
      --default

これでランナーの設定ファイルに ci という名前のプロファイルが書き込まれます。1 つのジョブの中ではステップをまたいでファイルシステムが保持されるため、そのジョブの以降のステップは再認証なしで atlassian-cli を呼び出せます。GitHub はログ上のシークレットの値を自動でマスクし、使い捨てのランナーが破棄されると認証情報も消えます。フラグの詳細は認証とプロファイルにあります。

ログインの直後に軽い確認を挟んでおけば、Jira の処理の途中まで進んでから失敗するのではなく、無効または期限切れのトークンでジョブを早期に落とせます。

# Exit non-zero if credentials are invalid
- name: Verify Jira auth
  run: atlassian-cli auth test --profile ci --format quiet

デプロイ時に課題を遷移させる

中心となる操作は、現実に何かが起きたときに課題をワークフローの新しいステータスへ動かすことです。それが jira issue transition で、課題キーと遷移名を受け取ります。

atlassian-cli jira issue transition DEV-123 --transition "Deployed"

遷移名は、その課題のワークフローに実在するものと一致していなければなりません（たとえば「Deployed」「Done」「In Review」など）。プロジェクトで使える名前を確認するには、手元で atlassian-cli jira workflows list を実行するか、ボードの設定を見ます。

実際のパイプラインでは課題キーを直書きしません。よく使われる慣習は、ブランチ名やコミットメッセージにキーを含めておき（DEV-123 fix login redirect）、実行時に取り出すことです。

# Pull the first PROJECT-NUMBER token from the latest commit subject
- name: Resolve issue key
  id: jira
  run: |
    KEY=$(git log -1 --pretty=%s | grep -oE '[A-Z]+-[0-9]+' | head -1)
    echo "key=$KEY" >> "$GITHUB_OUTPUT"

- name: Move issue to Deployed
  if: steps.jira.outputs.key != ''
  run: atlassian-cli jira issue transition ${{ steps.jira.outputs.key }} --transition "Deployed"

このステップはデプロイのステップより後に動き、失敗したステップは既定でジョブを止めるため、遷移は実際にデプロイが成功したときにしか発火しません。切り戻したリリースに対してボードが「Deployed」を表示することはありません。

ビルド状況を Jira にコメントする

ステータスの変更は課題がどこにあるかを伝え、コメントは何が起きたかを伝えます。jira issue comments add のサブコマンドは課題にコメントを投稿し、本文を --body で受け取ります。

atlassian-cli jira issue comments add DEV-123 \
  --body "Deployed to production. Build passed."

これを CI で行う価値は文脈にあります。GitHub Actions の変数を埋め込んでおけば、コメントから課題を、それを生んだコミットとパイプライン実行に直接ひも付けられます。

- name: Comment deploy status on Jira
  if: steps.jira.outputs.key != ''
  run: |
    atlassian-cli jira issue comments add ${{ steps.jira.outputs.key }} \
      --body "Deployed ${{ github.sha }} to production. Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

これで Jira の課題を読む人は、どのコミットが出荷されたかを正確に把握でき、そのままログまでたどれます。if: failure() を付けたステップを足せば失敗時にもコメントを投稿できるので、壊れたビルドが Actions タブの中で静かに消えるのではなく、課題に痕跡を残します。

パイプラインのイベントと CLI コマンドの対応

CI から Jira への自動化のほとんどは、こうした部品をいくつか別々のトリガーにつないだものです。次の表は、よくあるパイプラインの場面と、それを担当するコマンドの対応です。

デプロイワークフローの全体像

ここまでの部品をつないだ、端から端までの .github/workflows/deploy.yml を示します。インストール、認証、デプロイ、そして Jira の更新という流れです。main への push で動きます。

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install atlassian-cli
        run: cargo install atlassian-cli

      - name: Authenticate to Jira
        env:
          JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
          JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
        run: |
          atlassian-cli auth login \
            --profile ci \
            --base-url "$JIRA_BASE_URL" \
            --email "$JIRA_EMAIL" \
            --token "$JIRA_API_TOKEN" \
            --default
          atlassian-cli auth test --profile ci --format quiet

      - name: Resolve issue key
        id: jira
        run: |
          KEY=$(git log -1 --pretty=%s | grep -oE '[A-Z]+-[0-9]+' | head -1)
          echo "key=$KEY" >> "$GITHUB_OUTPUT"

      - name: Deploy application
        run: ./scripts/deploy.sh

      - name: Update Jira on success
        if: success() && steps.jira.outputs.key != ''
        run: |
          atlassian-cli jira issue transition ${{ steps.jira.outputs.key }} --transition "Deployed"
          atlassian-cli jira issue comments add ${{ steps.jira.outputs.key }} \
            --body "Deployed ${{ github.sha }} in run ${{ github.run_id }}."

      - name: Flag Jira on failure
        if: failure() && steps.jira.outputs.key != ''
        run: |
          atlassian-cli jira issue comments add ${{ steps.jira.outputs.key }} \
            --body "Deploy failed in run ${{ github.run_id }}. See Actions logs."

末尾の 2 つの条件付きステップが、成功時の道筋と失敗時の道筋を分けています。デプロイが成功すれば課題は「Deployed」へ移り、コメントが付きます。失敗すればステータスはそのままで、何が起きたかだけが記録されます。より重いバッチ処理（完了したリリースに含まれる課題を一度にすべて遷移させるなど）については、コマンドラインから Jira API を呼び出すで、同じワークフローに流用できる JQL 起点の一括処理のパターンを扱っています。

GitHub Actions 以外でも使う

ここまでの内容に GitHub 固有のものはありません。atlassian-cli は単一のバイナリなので、同じ 3 つの動作（インストール、シークレットストアの値での auth login、jira コマンドの実行）がどのランナーにも収まります。変わるのはシークレットとスクリプトの書き方だけです。最小限の GitLab CI のジョブは次のようになります。

# .gitlab-ci.yml
deploy:
  stage: deploy
  script:
    - cargo install atlassian-cli
    - atlassian-cli auth login --profile ci --base-url "$JIRA_BASE_URL" --email "$JIRA_EMAIL" --token "$JIRA_API_TOKEN" --default
    - atlassian-cli jira issue transition "$CI_ISSUE_KEY" --transition "Deployed"

まったく同じやり方が Jenkins（Credentials Binding プラグインで認証情報を注入）、CircleCI（コンテキストまたはプロジェクトの環境変数）、Bitbucket Pipelines（リポジトリ変数）でも通用します。シェルを実行できてシークレットを持てる CI であれば、Jira を動かせます。各製品の全コマンドはコマンドリファレンスにあります。

よくある質問

関連リソース