atlassian-cli 0.4 の新機能: Markdown から ADF への変換、Confluence フォルダー、カスタムパイプライン

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

atlassian-cli の 0.4 系では、これまで生の REST 呼び出しに戻らざるを得なかったいくつかの不足を解消しました。この記事では 0.4.0 と、その後の 0.4.1 で入った変更をまとめて紹介します。バージョンごとの一覧は変更履歴にあります。

アップグレード

# Homebrew
brew upgrade atlassian-cli

# Cargo
cargo install atlassian-cli

# Confirm
atlassian-cli --version

Linux と macOS 向けのビルド済みバイナリは GitHub の Releases ページにあります。

Jira: Markdown が本物の ADF になる

Jira Cloud はリッチテキストを ADF（Atlassian Document Format）として保存します。これまで --description は渡された内容をひとつのフラットな段落に包むだけだったため、見出しもリストも太字も失われていました。0.4 では CLI が Markdown を解析し、説明文とコメントを構造化された ADF として送信します。

# A Markdown file with headings, lists, and emphasis...
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Provision SFTP access" \
  --description "$(cat notes.md)"

# ...now renders as headings, bullet lists, bold, links, and code
# blocks in Jira instead of one wall of text.

Markdown 記法を含まないプレーンテキストはこれまでどおり単一の段落になるため、既存のスクリプトの挙動は変わりません。対応するノードは、見出し、箇条書きと番号付きリスト、コードブロック、引用、そして strong/em/code/link のマークです。生の ADF を直接送りたい場合は、低レベルの逃げ道として --field 'description=<json>' が引き続き使えます。

Confluence: Folder コマンドグループ

Confluence v2 API では、フォルダーはページとは別の独立したコンテンツタイプとして扱われ、専用のエンドポイントを持ちます。0.4 より前は到達する手段がなく、フォルダーの ID を page get に渡すと 404 が返っていました。専用の confluence folder グループが追加されています。

# Fetch folder metadata by ID
atlassian-cli confluence folder get 3309240341

# Create a folder in a space (the space key is resolved to an ID)
atlassian-cli confluence folder create \
  --space DOCS \
  --title "Architecture" \
  --parent 3302031761

# Delete (moves the folder to the trash; restorable)
atlassian-cli confluence folder delete 3309240341 --force

同じリリースで Confluence の一覧解析（page list、space list、検索）も強化しました。1 行に欠落した値や null のフィールドがあっても、レスポンス全体が中断されることはなくなりました。

Bitbucket: カスタムパイプラインを起動する

bitbucket-pipelines.yml の definitions > pipelines > custom に定義したパイプラインは、CLI から起動できませんでした。pipeline trigger コマンドに、API のセレクターを渡す --custom-pipeline フラグが追加されました。

# Run a named custom pipeline on a branch
atlassian-cli bitbucket --workspace myteam \
  pipeline trigger api-service \
  --ref-name main \
  --custom-pipeline s3-access-test

0.4.1: Jira の添付ファイルとコメント全文

0.4.1 のパッチでは、生の curl が必要だった箇所をさらに 2 つ解消しました。jira issue get が attachments の配列（ID、ファイル名、MIME タイプ、サイズ、ダウンロード URL）を含むようになり、comments list には短いプレビューではなく本文全体を取得する --full フラグが追加されました。

# Pull attachment metadata straight from issue get
atlassian-cli jira issue get DEV-428 --format json | jq '.attachments'

# Read full comment bodies, not the 50-character preview
atlassian-cli jira issue comments list DEV-428 --full

ここでの解析は意図的に寛容にしてあります。Jira は添付ファイルの id を数値で返すレスポンスと文字列で返すレスポンスがあり、0.4.1 はどちらも受け付けます。そのため、添付ファイルのある課題で issue get が失敗することはありません。

特筆すべき修正: HTTP 204 がエラーに見えなくなった

Jira を自動化しているなら、この修正のためだけでもアップグレードする価値があります。更新系のエンドポイント（issue update、transition、assign、および Confluence の対応するコマンド）は、成功時に 204 No Content を返します。クライアントはその空のボディを JSON として解析しようとしていたため、書き込みは成功しているのに error decoding response body と表示され、非ゼロで終了していました。終了コードを見ているスクリプトには、実際には起きていない失敗が見えていたわけです。

0.4 では空の 2xx ボディを成功として扱うため、すべての書き込みコマンドで終了コードが信頼できるようになりました。

細かな整備

保守されていない推移的依存 proc-macro-error2（RustSec のアドバイザリで指摘されていました）を削除し、本番向けの依存関係一式を更新しました。
すべてのリリースは、Linux と macOS でのビルドとテスト、そしてセキュリティ監査をクリアしたうえで公開しています。

謝辞

0.4 は、明確な報告とプルリクエストを送ってくれた方々によって形になりました。HTTP 204 の不具合、構造化 ADF の要望、Folder API の要望、カスタムパイプラインのフラグ（とその PR）、添付ファイルとコメント全文の要望は、いずれもコミュニティから寄せられたものです。ありがとうございます。個別の謝辞はリリースノートに記載しています。

バージョンごとの変更点の全一覧は変更履歴をご覧ください。各コマンドをさらに詳しく知りたい場合は、コマンドリファレンスに新しいフォルダー、パイプライン、コメントのオプションを掲載しています。

atlassian-cli をインストールまたはアップグレード

Jira、Confluence、Bitbucket、JSM をひとつの CLI で。MIT ライセンスのオープンソースです。

はじめる