プラグインの自動リリース

自動リリースは、バージョンタグをプッシュしたとき、または GitHub Actions ワークフローを手動で開始したときに、サンドボックスプラグインをビルドして公開します。Atmosphere アカウントは引き続きパッケージプロファイルとリリース記録の所有者です。GitHub が承認済みワークフローを識別し、リリースサービスがビルドを検証して、狭い委任を通じてリリースを書き込みます。リポジトリに Atmosphere アカウントの資格情報は保存されません。

コンピューターから開始するリリースには emdash-plugin publish を使用します。GitHub Actions がリリースをビルドおよび公開する場合はこのガイドを使用します。

前提条件

開始前に次を用意してください。

• サンドボックス化された 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 は、workflow_call 経由で Changesets Action の公開パッケージ JSON を受け付けます。既存の 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 は camel-case の 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. パッケージプロファイルが存在し、パブリッシャーによって署名され、delegated-release 設定を含み、同じ正規 GitHub リポジトリを指定していること。
3. 要求されたパッケージとバージョンがビルド済みプラグインバンドルと一致すること。
4. パッケージのチェックサムがアップロードされたバイトと一致すること。
5. GitHub provenance が同じバンドル、リポジトリ、ワークフロー、コミット、実行をカバーしていること。
6. リリース記録の宣言されたアクセスがバンドルマニフェストと一致すること。
7. バージョン記録がまだ存在しないこと。
8. 必要なパスキー承認が、正確な検証結果と現在のプロファイルリビジョンをカバーしていること。

Action はサービス呼び出しごとに新しい GitHub OIDC トークンを要求します。バンドルと provenance ファイルは、ワークフローが認可された後にのみプライベートな一時ストレージに入ります。サービスは検証済みのパッケージと画像バイトをパブリッシャーのパーソナルデータサーバー (PDS) にアップロードし、そこにリリース記録を作成し、チェックサムアドレスの不変 URL を通じて検証済み provenance を公開します。

権限の境界

各資格情報には 1 つの役割があります。

サービスはパブリッシャーと承認者の状態を別々に保存します。リリースを表示するためのサインインはオペレーターアクセスを付与せず、オペレーターの ID はパブリッシャーとしてリリースを承認できません。

Action の動作

生成されたワークフローは apps/release-action の Action を使用します。Action はビルド済みバンドルと生の Sigstore provenance、またはチェックサムにバインドされた HTTPS アーティファクトソースを含む互換 release-file のいずれかを受け付けます。release-file をバンドルまたは provenance 入力と組み合わせないでください。

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

Action はこれらの出力を返します。

オプション入力、カスタム URL ソースワークフロー、ポーリング制御、正確な出力動作については Action リファレンス を参照してください。

トラブルシューティング

PACKAGE_PROFILE_REQUIRED

パッケージプロファイルがない、delegated-release 設定がない、非正規のリポジトリ URL を使用している、または GitHub ワークフローと異なるリポジトリを指定しています。

パブリッシャーアカウントでローカルにプロファイルセットアップを実行してから、ワークフローを再開始します。

pnpm exec emdash-plugin profile setup

このチェックは、サービスがバンドルまたは provenance のアップロードを受け入れる前に実行されます。

公開リポジトリが必要

GitHub はプライベートおよび内部リポジトリにプライベート Sigstore 信頼ルートを使用します。リリース検証器は現在、公開 GitHub provenance のみを信頼します。リリースワークフローを公開リポジトリに移すか、emdash-plugin publish でローカルに公開してください。

WORKLOAD_NOT_ALLOWED

GitHub リポジトリ、所有者、ワークフローファイル、ref、または環境が承認済みワークフローポリシーと一致しません。リリースダッシュボードを開き、意図したスコープで新しいワークフロー接続を承認してください。

PROFILE_FETCH_FAILED

サービスがパブリッシャーの PDS からプロファイルを検証できませんでした。アカウントプロバイダーが利用可能になったら再試行してください。プロファイルが削除または変更された場合は emdash-plugin profile setup を実行します。

POLL_TIMEOUT

Action がワークフロー承認、リリース承認、または公開の完了前に timeout-minutes に達しました。再実行する前にリリースダッシュボードで intent の状態を確認してください。同じ GitHub Actions 実行の再実行はその冪等キーを再利用します。

自動公開の取り消し

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

次の自動リリースの前に、公開を再接続し、ワークフローを再度承認してください。

関連ドキュメント

• Bundling and publishing はローカル公開とバンドル検証を扱います。
• The plugin manifest はパッケージメタデータと宣言されたアクセスを定義します。
• Capabilities and security はリリース承認とインストール時にレビューされる権限を説明します。
• The plugin registry は発見、モデレーション、インストール検証を説明します。