自動リリース

前提条件

始める前に、次のものを用意します。

• サンドボックス型のEmDashプラグインを含む、公開のGitHubリポジトリ。
• 開発用の依存パッケージとしてインストールした @emdash-cms/plugin-cli。CLIで作成したプラグインには、最初から含まれています。
• slug、publisher、license、作者、セキュリティの連絡先を含む、有効なemdash-plugin.jsonc。repo に正規のGitHubのURLを設定するか、対話形式のセットアップで検出されたGitHubのリモートを確認します。
• package.json のバージョン。レジストリ専用のプラグインでは emdash-plugin.jsonc のバージョン。
• publisher で指定したAtmosphereアカウント。
• パスキーに対応したブラウザー。リリースの承認には、ユーザーの本人確認が必要です。

ワークフローを設定する前に、マニフェストの確認を実行します。

pnpm exec emdash-plugin validate

自動リリースの設定

Changesetsのワークフローとの連携

生成された .github/workflows/emdash-release.yml は、Changesets Actionが出力する公開済みパッケージのJSONを、workflow_call で受け取ります。既存のChangesetsのジョブに出力を追加し、それに依存するジョブからEmDashのワークフローを呼び出します。既存のジョブやステップが別のIDを使っている場合は、release と changesets を置き換えます。

Changesets Action v2は、published-packages という出力を使います。Changesets CLI v3を使うワークフローには、次のジョブの出力と呼び出し側のジョブを追加します。

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs['published-packages'] }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

Changesets Action v1は、キャメルケースの publishedPackages というステップの出力を使います。Changesets CLI v2を使うワークフローでは、次の式を使います。

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs.publishedPackages }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

バージョンのプルリクエストとパッケージの公開は、引き続きChangesetsに任せます。EmDashを呼び出すジョブは、Changesetsが published: true を報告したときだけ実行されます。EmDash専用の非公開パッケージの場合は、.changeset/config.json で privatePackages.version と privatePackages.tag の両方を true にします。関係のない非公開のアプリケーションやテスト用のフィクスチャーは、ignore に追加します。

パッケージの追加

パッケージのソースのディレクトリで、そのパッケージのプロフィールを準備します。ルートにある既存のワークフローと、リポジトリの接続が再利用されます。

pnpm exec emdash-plugin profile setup --dir packages/comments

Changesetsを使う場合は、パッケージをchangesetに追加し、そのバージョンのプルリクエストをマージします。パッケージのタグをきっかけにする場合は、パッケージのバージョンを更新して、そのタグをプッシュします。

git tag comments@1.0.0
git push origin comments@1.0.0

ワークフローは、comments を1つの emdash-plugin.jsonc に対応付け、選択したバージョンを確認し、成果物のアップロードを受け付ける前に、署名されたプロフィールに接続済みのリポジトリが書かれていることを検証します。パッケージIDの重複やバージョンの不一致は、アテステーション（attestation）の前に失敗します。

リリースサービスが検証すること

サービスは、リリースを書き込む前に次の確認を済ませます。

1. GitHubのOpenID Connect（OIDC）トークンに、認可されたリポジトリ、所有者、ワークフロー、ref、環境、コミット、実行、GitHubがホストするランナーが示されている。
2. パッケージのプロフィールが存在し、公開者が署名しており、委任によるリリースの設定を含み、同じ正規のGitHubリポジトリが書かれている。
3. 要求されたパッケージとバージョンが、ビルドされたプラグインのバンドルと一致する。
4. パッケージのチェックサムが、アップロードされたバイト列と一致する。
5. GitHubの来歴が、同じバンドル、リポジトリ、ワークフロー、コミット、実行を対象にしている。
6. リリースのレコードで宣言されたアクセスが、バンドルのマニフェストと一致する。
7. そのバージョンのレコードがまだ存在しない。
8. 必要なパスキーによる承認が、検証結果そのものと、現在のプロフィールの版を対象にしている。

Actionは、サービスを呼び出すたびに新しいGitHubのOIDCトークンを要求します。バンドルと来歴のファイルは、ワークフローが認可されたあとでのみ、非公開の一時的なストレージに入ります。サービスは、検証済みのパッケージと画像のバイト列を公開者の個人データサーバー（PDS）にアップロードし、そこにリリースのレコードを作成して、検証済みの来歴を、チェックサムで指定する変更不可のURLで公開します。

権限の境界

資格情報は、それぞれ1つの役割だけを持ちます。

サービスは、公開者の状態と承認者の状態を別々に保存します。自分のリリースを見るためにサインインしても運用者のアクセス権は得られず、運用者のIDで公開者としてリリースを承認することもできません。

Actionの動作

生成されたワークフローは、apps/release-action のActionを使います。このActionは、ビルドされたバンドルとSigstoreの来歴そのものの組み合わせか、チェックサムに結び付いたHTTPSの成果物の取得元を含む互換用の release-file のどちらかを受け付けます。release-file を、バンドルや来歴の入力と組み合わせないでください。

標準の生成されたワークフローは、次の入力を渡します。それぞれの値が何を認可するのかを推測せずに生成されたファイルを確認できるように、ここに示します。

Actionは、次の値を出力します。

省略可能な入力、URLを取得元にする独自のワークフロー、ポーリングの制御、出力の正確な動作については、Actionのリファレンスを参照してください。

トラブルシューティング

PACKAGE_PROFILE_REQUIRED

パッケージのプロフィールがない、委任によるリリースの設定がない、正規でないリポジトリのURLを使っている、またはGitHubのワークフローとは別のリポジトリが書かれている状態です。

公開者のアカウントでローカルでプロフィールのセットアップを実行し、ワークフローをもう一度開始します。

pnpm exec emdash-plugin profile setup

この確認は、サービスがバンドルや来歴のアップロードを受け付ける前に実行されます。

公開のリポジトリが必要

GitHubは、非公開（private）と社内（internal）のリポジトリには非公開のSigstoreの信頼ルートを使います。リリースの検証の仕組みは、現在、公開のGitHubの来歴だけを信頼します。リリースのワークフローを公開のリポジトリに移すか、emdash-plugin publish でローカルから公開します。

WORKLOAD_NOT_ALLOWED

GitHubのリポジトリ、所有者、ワークフローのファイル、ref、環境のいずれかが、承認済みのワークフローの方針と一致しません。リリースのダッシュボードを開き、意図した範囲で新しいワークフローの接続を承認します。

PROFILE_FETCH_FAILED

サービスが、公開者のPDSからプロフィールを検証できませんでした。アカウントのプロバイダーが利用できるようになってから再試行します。プロフィールが削除または変更された場合は、emdash-plugin profile setup を実行します。

POLL_TIMEOUT

ワークフローの承認、リリースの承認、公開のいずれかが完了する前に、Actionが timeout-minutes に達しました。再実行する前に、リリースのダッシュボードでインテントの状態を確認します。同じGitHub Actionsの実行を再実行すると、その実行のべき等キー（idempotency key）が再利用されます。

自動公開の取り消し

リリースのダッシュボードで「Turn off automated publishing」を選択します。取り消すと、保持されていたリリースの委任が消去されます。既存のパッケージのプロフィール、リリース、モデレーションのラベル、インストール済みのプラグイン、ダッシュボードへのログインは変わりません。

次の自動リリースの前に、公開をもう一度接続し、ワークフローをあらためて承認します。

関連ドキュメント

• バンドルと公開では、ローカルからの公開とバンドルの検証を説明しています。
• マニフェストでは、パッケージのメタデータと宣言するアクセスを定義しています。
• 権限（Capabilities）とセキュリティでは、リリースの承認とインストールのときに確認する権限を説明しています。
• プラグインレジストリでは、検索、モデレーション、インストール時の検証を説明しています。