鍵がローカルに無いPCから、共有メールボックスで「Drive の PDF を添付した返信下書き」を作り、人の確認後に送る（GitHub Actions + ドメイン全体の委任）

こんな時に使う

• 返信を送るのは共有メールボックス（例: <共有アドレス>@<自社ドメイン>）だが、作業PCにはそのメールボックスの OAuth トークンも、サービスアカウント鍵も無い
• 鍵は GitHub リポジトリのシークレットにだけある（例: GOOGLE_SA_JSON。中身が base64 のこともある）
• 添付は Google Drive 上の PDF。AI のコネクタで添付を base64 で手渡しすると、書き写しの途中で壊れる
• 送信前に人が文面と添付を確認したい

前提

• サービスアカウントにドメイン全体の委任があり、次のスコープが管理コンソールで許可済み
  • https://www.googleapis.com/auth/gmail.compose
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/drive
• そのリポジトリに push できる（gh auth status で確認する）

手順

1. 使い捨てブランチを main から作る: gh api -X POST repos/<owner>/<repo>/git/refs
2. スクリプトを置く（npm 依存なし、node:crypto だけ）。中身は次のとおり。
   • トークン取得: RS256 の JWT を自作する（iss=SA のメール、sub=成り代わる人、scope=空白区切り）。それを https://oauth2.googleapis.com/token に grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer で送る
   • PDF 取得: GET drive/v3/files/<id>?alt=media&supportsAllDrives=true。sub はファイル所有者にする。ダメなら共有メールボックスで再試行
   • 元メールのヘッダ取得: messages/<id>?format=metadata&metadataHeaders=Message-ID&metadataHeaders=References&metadataHeaders=Subject
   • MIME を組む: multipart/mixed。本文は text/plain; charset=UTF-8（base64）。添付は Content-Disposition: attachment; filename*=UTF-8''<encodeURIComponent(名前)>。件名は =?UTF-8?B?…?= にする。In-Reply-To と References も付ける
   • 下書き作成: POST users/me/drafts に {message:{threadId, raw: base64url(mime)}}
   • 読み戻し: drafts/<id>?format=full で宛先・件名・スレッド・添付サイズを JSON に出し、actions/upload-artifact で回収する
3. workflow を置く: on: push: branches: [<使い捨てブランチ>] にする。workflow_dispatch は既定ブランチにファイルが無いと 404 になるので使わない。シークレットは env: で渡す
4. 結果を回収して確かめる: gh run watch <id> --exit-status → gh run download <id> -D out。添付のサイズが元 PDF と一致するかを見る
5. 人が下書きを確認する。OK が出たら、同じ型のスクリプトで次を行う
   • 送る直前に下書きの宛先とスレッドを照合し、違えば送らない
   • POST users/me/drafts/send {id} で送る
   • messages/<id> で SENT ラベルと添付を読み戻す
6. ブランチを削除する: gh api -X DELETE repos/<owner>/<repo>/git/refs/heads/<branch>。シークレットを使える workflow を残さないため

ハマりどころ（実測）

• スコープを gmail.compose だけにすると、元メールの metadata 取得が 403 になる（insufficient scopes）。gmail.compose gmail.readonly を空白区切りで両方要求する
• Contents API でファイルを1つずつ PUT すると1回ずつ commit になり、workflow がある枝では commit ごとに run が立つ。3本並走して二重下書きになりかけた。対策は次のとおり
  • workflow ファイルを最後に置く（最初の push では workflow がまだ無いので run が立たない）
  • 再 push する時は concurrency: を付けるか、余分な run をすぐ gh run cancel する
  • 作成後は下書き一覧を宛先で検索し、1通だけかを確かめる
• シークレットが base64 のことがある。先頭が { でなければ復号してから JSON.parse する
• 古い下書きを消すのは、新しい下書きの読み戻しで添付と threadId を確認できてからにする