[furedea-agent]

概要

• release-please がタグと draft の Release を作り，そのタグ上で Release Artifacts ワークフローを起動する．macOS ランナーで aarch64-apple-darwin の cargo-dist アーカイブをビルド，検証，attestation，アップロードし終えてから Release を公開する．
• 成果物ワークフローは自動でも手動でも常にタグ上で動き，draft の Release にしか触れない．公開済みの Release は作り直さず，修正は新しい版で出す．
• マージ前にリポジトリシークレット RELEASE_PLEASE_TOKEN の登録が必要．未登録のままマージすると release-please ジョブが失敗する．

flowchart LR
  A[main へ push] --> B[release-please が Release PR を作成]
  B -->|マージ| C[タグ apple-mail-cli-vX.Y.Z と draft Release]
  C --> W[gh workflow run release_artifacts.yml --ref タグ]
  M[失敗した draft の再開も同じコマンド] --> W
  W --> V[ref，HEAD，draft の検証]
  V --> D[macos-15 で cargo test --locked と pnpm run check]
  D --> E[dist build とアーカイブのスモークテスト]
  E --> G[attest-build-provenance]
  G --> H[gh release upload --clobber]
  H --> P[gh release edit --draft=false で公開]

Loading

項目	変更前	変更後
バージョン管理	Cargo.toml 0.1.0，flake は直書き	release-please が Cargo.toml と CHANGELOG を更新，flake は Cargo.toml から読む
Release の公開	なし	draft で作成し，全ステップ成功後に公開．失敗時は draft のまま
成果物のビルド	なし	release_artifacts.yml をタグ上で起動（自動・手動で同じ経路）
配布物	なし	tar.xz，.sha256，sha256.sum，source.tar.gz，シェルインストーラー
来歴証明	なし	actions/attest-build-provenance．常にタグのコミットを記録
インストール方法	cargo install --path .，nix run	curl インストーラー，cargo install --locked --git，nix profile install
CI のピン	checkout v6.0.2，rust-toolchain v1.16.0，stable，cargo test	checkout v6.1.0，rust-toolchain v1.17.0，1.98.1，cargo test --locked

受け入れ条件

• マージ前に RELEASE_PLEASE_TOKEN シークレットを登録する（下記「シークレット登録」参照）
• release-please-config.json と .release-please-manifest.json（0.1.0）を追加
• main への push で Release PR が作られる（シークレット登録とマージ後に確認）
• リリース時に macOS ランナーで cargo test --locked とビルドが通り，アーカイブで apple-mail --version が成功する（ローカルの dist build では確認済み）
• Release は成果物のアップロード後に公開され，アーカイブ，.sha256，インストーラーが添付され，gh attestation verify が通る
• 失敗した draft は gh workflow run release_artifacts.yml --ref <tag> -f tag_name=<tag> で再開できる．タグ以外の ref や公開済みの Release では失敗する
• flake の version が Cargo.toml から読まれる
• README のインストール節と CONTRIBUTING.md を更新・追加する

詳細

シークレット登録

GITHUB_TOKEN で作った Release PR では CI が起動しないため，agent-harness と同じく PAT を使う．

• 名前：RELEASE_PLEASE_TOKEN（リポジトリシークレット）
• 種類：fine-grained personal access token，対象は furedea/apple-mail-cli のみ
• 権限：Contents，Pull requests，Issues をそれぞれ Read and write（Metadata: Read は自動付与）
• 登録：gh secret set RELEASE_PLEASE_TOKEN --repo furedea/apple-mail-cli

成果物ワークフローの起動には GITHUB_TOKEN（actions: write）を使う．workflow_dispatch は GITHUB_TOKEN からでも新しい実行を作れるので，PAT の権限を増やす必要はない．

ワークフローの構成

• release_please.yml（main への push）：release-please で Release PR，タグ，draft Release を作る．release_created のときだけ gh workflow run release_artifacts.yml --ref "$TAG_NAME" -f tag_name="$TAG_NAME" を実行する
• release_artifacts.yml（workflow_dispatch のみ）：テスト，ビルド，スモークテスト，attestation，アップロード，公開．concurrency はタグごと
• ジョブを分けた理由：一つのワークフロー内だと，Release PR のマージコミット R の待機中の実行が後続の push S に置き換わったとき，S の実行は HEAD=R，GITHUB_SHA=S となってガードで失敗する．release-please は PR を tagged 済みにしているので，以後 release_created は立たず draft が取り残される．タグ上で起動すれば GITHUB_SHA は常にタグのコミットになる

draft から公開までの流れ

• release-please-config.json に "draft": true と "force-tag-creation": true を設定．draft でもタグがすぐ作られるため，成果物ワークフローをタグ上で起動でき，次回の release-please も前回リリースを見つけられる（force-tag-creation は release-please v17.2.0 で追加，固定中の action v4.4.1 は ^17.3.0 を同梱）
• release-please はマージ済み Release PR のラベル（autorelease: pending → tagged）でリリース作成を判断するため，draft でも重複作成しない
• ジョブの最後に gh release edit "$TAG_NAME" --draft=false を実行．途中で失敗すれば draft のまま残り，README の releases/latest の URL が欠けた成果物を指すことはない

Verify release target ステップ（checkout 直後，ビルド前）

• GITHUB_REF が refs/tags/$TAG_NAME でなければ失敗し，正しいコマンドを表示する
• checkout した HEAD が GITHUB_SHA と一致しなければ失敗する
• gh release view "$TAG_NAME" --json isDraft が true でなければ失敗する．--clobber は各アセットを消してから上げ直すため，公開済みの Release を作り直すとネットワーク障害で欠けた Release が残りうる

変更ファイル

• .github/workflows/release_please.yml，.github/workflows/release_artifacts.yml（ともに新規），release-please-config.json，.release-please-manifest.json
• Cargo.toml：[profile.dist]，[workspace.metadata.dist]（target aarch64-apple-darwin，shell installer，cargo-dist 0.30.2）
• flake.nix：version を Cargo.toml から読む
• .github/workflows/{ci,codeql,dependency_review,gha_lint}.yml：ピンそろえ，cargo test --locked
• .ls-lint.yml：慣習名の CONTRIBUTING.md，CHANGELOG.md，release-please-config.json を除外
• README.md，CONTRIBUTING.md

agent-harness との差分

• ランナーは macos-15，musl/apt 手順なし，リリースジョブで JXA チェック（pnpm run check）も実行
• draft から公開する流れ，タグ上で動く成果物ワークフロー，draft のみを対象とするガードは agent-harness にはない（agent-harness にも同じ問題がある）
• macOS ランナーの /bin/bash は 3.2 で mapfile がないため，アップロード一覧は while read で配列化
• リリースジョブでは setup-node のキャッシュを使わない

ローカル検証

• cargo test --locked，cargo fmt --check，cargo clippy --locked --all-targets -- -D warnings：成功
• pnpm run check，nixfmt，statix，deadnix，ls-lint，commitlint：成功
• nix flake check：成功，nix build .# で apple-mail-cli-0.1.0 をビルド
• actionlint，zizmor --offline：指摘なし
• Verify release target の本体を /bin/bash 3.2 と偽の gh で 6 ケース検証（ref が main，別タグ，SHA 不一致，公開済み，draft 状態が空は失敗，タグ上で SHA 一致かつ draft は成功）
• nixpkgs の cargo-dist 0.31.0（一時 worktree で cargo-dist-version のみ合わせる）で dist plan と，ワークフローと同じ dist build 手順を実行し，アーカイブ展開後の apple-mail --version/--help と shasum -a 256 -c が成功．アップロード対象は 6 ファイル

CI や実リリースでしか確認できないこと

• cargo-dist 0.30.2 のインストーラーと macos-15 ランナーでの実行
• release-please の Release PR 作成，draft Release とタグの作成，タグ名（apple-mail-cli-vX.Y.Z を想定）
• GITHUB_TOKEN による gh workflow run --ref <tag> の起動，draft Release への gh release view/upload/edit --draft=false，公開後の latest の切り替わり，attestation
• 最初のリリース版：既存タグがないため，feat コミットと bump-patch-for-minor-pre-major により 0.1.1 が提案される見込み

除外

• Developer ID 署名と公証，Homebrew tap，crates.io 公開，SECURITY.md，Issue テンプレート，CI での Mail E2E テスト

Closes #7

🤖 Generated with Claude Code