release-mac-app

Mac アプリのリリース

BlackBar、RepoBar、CodexBar、Trimmy など、Sparkle で更新する macOS アプリに使用します。

ルール

• アプリのリポジトリで作業します。
• リポジトリが管理するリリースマニフェストである .mac-release.env を読みます。
• リリース、アプリキャスト、検証に関する共通作業には、このスキルの scripts/mac-release を使用します。
• mac-release を直接実行し、特権付きの Bash シバンで起動時のフックを無視させます。明示的なインタープリターが避けられない場合は、/bin/bash -p を使用し、通常の bash mac-release は使用しないでください。
• アプリ固有のビルド、パッケージ、署名の処理は、すでにマニフェストで管理されている場合を除き、リポジトリのスクリプトに保持します。
• 秘密鍵の内容を決して出力しないでください。
• アプリと dSYM のアセットは、公開前にドラフトにアップロードします。失敗した場合は、リリース、タグ、アプリキャストのコミット、ローカルの編集を保持してください。既存の状態を調べ、公開済みの可能性があるリリースを削除したり、タグを付け直したりせず、失敗した手順から再開します。
• ヘッドレスでリリースに署名する場合、鍵が 1Password にあるなら MAC_RELEASE_SPARKLE_OP_REF を優先します。それ以外の場合は、Keychain による Sparkle 署名を優先します。SPARKLE_PRIVATE_KEY_FILE は、明示的に指定するローカルの上書き設定に限ります。

コマンド

/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release status
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release notes [version] [output.md]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release changelog-html <version> [CHANGELOG.md]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release make-appcast <zip> [feed-url]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release verify-appcast [version]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release check-assets [tag]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release release
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release codesign-run [--with-package-secrets] -- <command> [args...]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release package-run -- <command> [args...]

マニフェスト

各リポジトリで .mac-release.env を管理します。ここにシークレットを含めてはいけません。

必須項目：

• MAC_RELEASE_APP_NAME
• MAC_RELEASE_REPO
• MAC_RELEASE_BUNDLE_ID
• MAC_RELEASE_VERSION_FILE
• MAC_RELEASE_APPCAST
• MAC_RELEASE_FEED_URL
• MAC_RELEASE_DOWNLOAD_URL_PREFIX
• MAC_RELEASE_APP_ZIP
• MAC_RELEASE_INFO_PLIST または MAC_RELEASE_SUPUBLIC_ED_KEY のいずれか
• MAC_RELEASE_PACKAGE_CMD

一般的な任意項目：

• MAC_RELEASE_PRECHECK
• MAC_RELEASE_SOURCE_FILES (成果物名を展開する前に source する、スペース区切りのアプリヘルパーファイル)
• MAC_RELEASE_DSYM_ZIP
• アプリのみのリリースでは MAC_RELEASE_REQUIRE_DSYM=0
• MAC_RELEASE_ARTIFACT_PREFIX
• MAC_RELEASE_TAG_SIGNED
• MAC_RELEASE_TAG_FORCE
• MAC_RELEASE_RELEASE_BRANCH
• MAC_RELEASE_SPARKLE_ACCOUNT
• MAC_RELEASE_SPARKLE_CHANNEL
• MAC_RELEASE_GENERATE_APPCAST_ARGS
• MAC_RELEASE_RUN_SPARKLE_UPDATE_TEST
• MAC_RELEASE_SPARKLE_OP_REF — Sparkle EdDSA 秘密鍵を指す正確な op://Vault/Item/field 参照。ヘルパーは共有の op-work tmux セッション内でこれを解決し、モード 0600 の一時キーファイルのみを書き出し、その公開鍵を SUPublicEDKey に対して検証し、成功時も失敗時も削除します。
• MAC_RELEASE_SPARKLE_OP_ACCOUNT と MAC_RELEASE_SPARKLE_OP_USE_SERVICE_ACCOUNT は、Sparkle 参照に対するプライマリの 1Password アカウント／サービスアカウントモードを上書きします。サービスアカウントベースの参照では、サービスアカウントモードを 1 に設定する必要があります。
• MAC_RELEASE_SIGNING_KEY_FILE (ローカルフォールバックパスのみ。ファイルが存在しない場合は Keychain が使用されます)
• MAC_RELEASE_EXTRA_ASSET_PATTERNS
• MAC_RELEASE_EXTRA_ASSET_WAIT_SECONDS
• MAC_RELEASE_EXTRA_ASSET_WAIT_INTERVAL
• MAC_RELEASE_OP_ENV_REFS — 同じ資格情報パスで解決され、パッケージコマンド用にエクスポートされる、';' 区切りの NAME=op://Vault/Item/field エントリ (アイテム名にスペースを含められるため ';')。すでにエクスポート済みの名前が優先され、参照は存在しない場合にのみ op read をトリガーします。例: NPM_TOKEN=op://Molty/npm Registry - steipete - Release Automation/registry_token。
• 必須のパッケージングシークレットには MAC_RELEASE_OP_ITEM + MAC_RELEASE_OP_FIELDS。リリースヘルパーは、1 つの永続的な tmux セッション内で op を介して既知のアイテムを一度読み取り、要求されたフィールドをパッケージコマンド用にエクスポートします。
• MAC_RELEASE_OP_ACCOUNT のデフォルトは my.1password.com です。MAC_RELEASE_OP_VAULT、MAC_RELEASE_OP_TMUX_SESSION、MAC_RELEASE_OP_WAIT_SECONDS は任意です。vault がない場合、その単一の op 読み取りに対してサービスアカウントトークンの環境変数が未設定になり、個人のデスクトップアカウントが処理します。
• MAC_RELEASE_CODESIGN_IDENTITY + MAC_RELEASE_CODESIGN_OP_ITEM + MAC_RELEASE_CODESIGN_KEYCHAIN_MANAGED=1 で、非対話的な Developer ID 署名が有効になります。keychain は交換可能で、リリース自動化専用であり、デフォルトの keychain とは別であり、対話的な使用と共有されておらず、署名用秘密鍵をちょうど 1 つ含んでいる必要があります。ヘルパーはそのキーのパーティション ACL を所有し、apple-tool:,apple:,codesign: に恒久的に正規化する場合があります。precheck 後、同じ tmux 資格情報パスが keychain_path と通常は keychain_password を読み取り、ユーザーごとのリリースロックを取得し、既存の keychain を隠さずに keychain を先頭に追加し、Developer ID Application のカナリアを検証し、一時的な codesign --keychain シムを通じてパッケージ署名をスコープし、その後、一時的な状態を復元してロックを解放します。MAC_RELEASE_CODESIGN_PASSWORDLESS=1 は、正規のパスワードレスで決してロックしないリリース keychain にのみ設定してください。これはパスワードフィールドを省略し、そのロック解除状態を保持し、タイムアウト／スリープ時ロック設定を無効にします。
• MAC_RELEASE_CODESIGN_OP_ACCOUNT、MAC_RELEASE_CODESIGN_OP_VAULT、MAC_RELEASE_CODESIGN_OP_USE_SERVICE_ACCOUNT、MAC_RELEASE_CODESIGN_OP_PATH_FIELD、MAC_RELEASE_CODESIGN_OP_PASSWORD_FIELD は codesign 資格情報アイテムのデフォルトを上書きします。アカウント、vault、サービスアカウントモードは、それ以外の場合はプライマリアイテムの設定を継承します。個人のデスクトップアカウントのアイテムには、vault を空に、サービスアカウントモードを 0 に設定してください。代わりに MAC_RELEASE_CODESIGN_KEYCHAIN + MAC_RELEASE_CODESIGN_KEYCHAIN_PASSWORD を直接指定することもできます。
• MAC_RELEASE_RUN_LOGIN_SHELL=1 はコマンドフックを bash -lc にオプトバックします。デフォルトのフックは env -u BASH_ENV bash -c を使用するため、シェルのスタートアップファイルがエクスポートされたリリースシークレットを上書きすることはできません。

1Password のルール:

• まず、すでにエクスポートされている環境変数を使用してください。MAC_RELEASE_OP_FIELDS がすべてそろっている場合は、op を呼び出しません。
• 不足しているフィールドがある場合は、リリース全体を通じて、設定済みのパッケージ項目とコード署名項目を 1 つの tmux コマンドで読み取ります。
• プロバイダーの標準エラー出力とパーサーの例外は破棄されます。読み取りに失敗した場合は、値やフィールド名を含めず、プロバイダー読み取り、JSON／スキーマ、不足フィールド、またはパーサー失敗の固定診断メッセージで処理を停止します。
• 環境変数への直接参照の受け渡しでは、Bash 3.2 で取得した値を安全に保持するために Bash の %q を使用します。ただし、コマンド置換では op read の出力末尾の改行が削除されます。
• 生成される環境ファイルやログに秘密鍵を露出させずに、MAC_RELEASE_SPARKLE_OP_REF を解決します。ヘルパーの境界を越えて渡されるのは、一時ファイルのパスだけです。
• 明示的なボールト、または MAC_RELEASE_OP_USE_SERVICE_ACCOUNT=1 が指定されている場合に限り、サービスアカウントモードを使用します。
• 新しいシェルで op の読み取りを再試行しないでください。明示的なユーザーの指示があった場合に限り、同じ tmux セッションから再実行してください。
• 準備されていない Developer ID キーチェーンのまま、リリースがアプリのパッケージ化に進むことを決して許可しないでください。リリース中に SecurityAgent のパスワードウィンドウを表示しないでください。まず署名のカナリアテストで失敗させてください。
• アプリ以外のリリーススクリプトでは、リポジトリにキーチェーンの設定をコピーせず、codesign-run を使用します。コード署名マニフェストのフィールドは、.mac-release.env または明示的な MAC_RELEASE_CODESIGN_* 環境設定で指定してください。デフォルトではコード署名の認証情報のみを読み込みます。ラップ対象のリリーススクリプトで設定済みのパッケージ／公証フィールドも必要な場合は、--with-package-secrets を指定して、1Password の同じ読み取りで取得してください。制限付きの署名カナリアテストを実行し、管理対象キーチェーンのシムを通じて codesign の使用範囲を限定し、復元して再ロックしてから戻ります。
• 署名処理が不要な場合は、公証／パッケージの認証情報に package-run を使用します。Developer ID キーチェーンの解決、準備、ロック解除は一切行わず、子プロセスから署名と Sparkle の権限を取り除きます。
• リリースの秘密情報を読み込む前に、シェルの xtrace と verbose モードを無効にします。キーチェーンや検索リストを変更する前にクリーンアップを有効にし、専用キーチェーンの元のロックポリシーとユーザーの検索リストを復元して、パッケージ化の後に再ロックします。

完了条件

• appcast エントリに URL、長さ、Sparkle 署名が含まれている。
• ダウンロードした enclosure が Sparkle で検証される。
• 展開したアプリが codesign、spctl、stapler validate を通過する。
• GitHub リリースに、アプリの zip、設定されている場合は dSYM の zip、さらにアプリ固有の追加アセットが含まれている。
• リリースノートが変更履歴の該当セクションと一致している。
• 検証済みリリースの後、アプリのリポジトリで変更履歴を次のパッチバージョンの Unreleased に更新する。