atlassian: 読み取り専用 JIRA + Confluence
使用タイミング
- ユーザーがチケット（
PROJ-123）を指定し、その最新ステータス、担当者、リンク、または最近のコメントが必要な場合。 - 新しいチケットフォルダにXMLが必要な場合：
data/changes/<ticket-小文字>/<TICKET>.xml。 - Confluenceにも存在するドキュメントを編集する前に：まず差分を確認する。
ツール
プロジェクトリポジトリ内の data/changes/tools/atlassian/atl.py（コースコピー：ejemplos/metodologia/tools/atlassian/）。
Python 3.10以上、標準ライブラリのみ（pipインストール不要）。リポジトリルートから実行。macOS、Linux、WSLでは python3、Windowsでは py または python を使用。
python3 data/changes/tools/atlassian/atl.py jira issue PROJ-123 # タイプ、ステータス、概要、担当者、リンク
python3 data/changes/tools/atlassian/atl.py jira search 'project = PROJ AND assignee = currentUser() AND statusCategory != Done'
python3 data/changes/tools/atlassian/atl.py jira links PROJ-123
python3 data/changes/tools/atlassian/atl.py jira comments PROJ-123 --last 3
python3 data/changes/tools/atlassian/atl.py jira xml PROJ-123 --out data/changes/proj-123/
python3 data/changes/tools/atlassian/atl.py confluence search 'title ~ "authoring" AND type = page'
python3 data/changes/tools/atlassian/atl.py confluence page <PAGE_ID> --body
python3 data/changes/tools/atlassian/atl.py confluence diff <local .md/.html> <PAGE_ID>
終了コード：
| コード | 意味 |
|---|---|
| 0 | 正常 |
| 2 | 認証情報が見つからないか無効（セットアップを参照） |
| 3 | HTTPエラー |
| 4 | 見つかりません |
--json は生のJSONを返します。スクリプト内でのみ使用してください。チャットでは、コンパクトなデフォルトでコンテキストを節約します。
セットアップ（マシンごとに一度、ユーザーが実行）
~/.config/<org>/jira.env（Windows：%USERPROFILE%\.config\<org>\jira.env；ATLASSIAN_ENV_FILE でパスを上書き可能）を作成し、3行を記述します：
JIRA_BASE_URL=https://<your-site>.atlassian.net
JIRA_EMAIL=<あなたのAtlassianログインメール>
JIRA_API_TOKEN=<token from id.atlassian.com → Security → API tokens>
自分のユーザーのみに制限します（macOS/Linuxでは chmod 600）。自分の端末で記述し、トークンをチャットや data/ 配下のファイルに絶対に貼り付けないでください。同じトークンでConfluenceも読み取れます。… atl.py jira issue PROJ-123 で確認：終了コード0で動作、コード2でファイルがないか間違っています。
ハードルール
- 読み取り専用。
atl.pyはGETのみを送信します（1つのネットワーク関数；テストで確認）。- JIRAチケットの作成、編集、状態遷移、コメント追加はユーザーの仕事です。テキストを下書きし、ユーザーが投稿します。
- 既存のConfluenceページの更新には
confluence_write.pyを使用します：pull→plan（バックアップ＋可視テキスト差分＋確認トークン）→ ユーザーが差分を読み、そのページを確認 →apply --confirm <token>。ユーザーが明示的にそのページの更新を依頼した場合のみ実行します。plan以降にトークン、本文ファイル、またはライブページのバージョンが変更された場合はapplyを拒否し、ページを読み直します。
- トークンや
jira.envの内容を印刷、貼り付け、ログに記録してはいけません。 - チケットはキーで引用します。 外部テキストではケースタグとチケットキーを引用し、ローカルファイルパスは使用しません。