自動化外掛發佈

自動化發佈會在你推送版本標籤或手動啟動 GitHub Actions 工作流程時，建置並發佈沙箱外掛。你的 Atmosphere 帳戶 仍擁有套件設定檔與發佈記錄。GitHub 識別已核准的工作流程，發佈服務驗證建置，並透過狹窄的委託寫入發佈記錄。儲存庫不會儲存 Atmosphere 帳戶憑證。

從你的電腦啟動發佈時，使用 emdash-plugin publish。當應由 GitHub Actions 建置並發佈時，使用本指南。

先決條件

開始前請準備：

• 包含沙箱 EmDash 外掛的公開 GitHub 儲存庫。
• 作為開發相依性安裝的 @emdash-cms/plugin-cli。用 CLI 建立的外掛已包含它。
• 有效的 emdash-plugin.jsonc，包含 slug、publisher、license、作者與安全性聯絡人。將 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 負責其版本提取要求與套件發佈。僅當 Changesets 回報 published: true 時，EmDash 呼叫方才執行。對於僅 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 解析為一個 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。

權限邊界

每種憑證各司其職：

服務分別儲存發佈者與核准者狀態。登入檢視你的發佈不會授予營運存取，營運身分也不能以發佈者身分核准發佈。

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 說明探索、審核與安裝驗證。