自動化外掛發佈

自動化發佈在你推送版本標籤或手動啟動 GitHub Actions 工作流程時建置並發佈沙箱外掛。你的 Atmosphere 帳戶擁有套件設定檔和發佈記錄。GitHub 識別已核准的工作流程，發佈服務在不將帳戶憑證儲存在儲存庫中的情況下驗證並發佈結果。

對於從你的電腦發起的發佈，使用 emdash-plugin publish。當 GitHub Actions 需要建置和發佈版本時，使用本指南。

前置條件

開始之前準備以下內容：

一個包含沙箱 EmDash 外掛的公開 GitHub 儲存庫。
一個有效的 emdash-plugin.jsonc，包含 slug、publisher、license、作者和安全聯絡人。將 repo 設定為規範的 GitHub URL，或在互動式設定期間輸入。
package.json 中的版本，或對於僅登錄檔外掛在 emdash-plugin.jsonc 中的版本。
publisher 指定的 Atmosphere 帳戶。
向儲存庫新增 GitHub Actions 密鑰的權限。
支援通行金鑰的瀏覽器。發佈審批需要使用者驗證。

在設定工作流程之前執行清單檢查：

pnpm exec emdash-plugin validate

設定自動化發佈

使用擁有該套件的 Atmosphere 帳戶登入外掛 CLI。
```
pnpm exec emdash-plugin login alice.example.com
```
CLI 將此本地發佈工作階段儲存在專案之外。GitHub Actions 永遠不會接收到它。
準備套件設定檔並產生工作流程。
```
pnpm exec emdash-plugin release setup
```
該命令從 emdash-plugin.jsonc 讀取套件中繼資料。如果套件設定檔缺失，它會提議建立。如果設定檔存在但沒有委託發佈設定，它會提議在保留現有套件中繼資料的同時新增這些設定。

設定會詢問何時需要審批發佈：
- 當外掛權限增加時 是預設選項。當宣告的存取權限相對於最新發佈擴展時，發佈等待審批。
- 每次發佈 要求每個版本都需要審批。
已登入的 Atmosphere 帳戶成為初始審批者。設定檔還將套件繫結到規範的 GitHub 儲存庫 URL，並要求可驗證的來源。

當工作流程檔案已存在時，僅執行設定檔步驟：
```
pnpm exec emdash-plugin profile setup
```
在非互動式終端中，傳遞 --yes 接受預設審批策略。當清單不包含 repo 時傳遞 --repository <https-url>，傳遞 --confirmation always 以要求每次發佈都需審批。
審查並提交產生的工作流程。

該命令建立 .github/workflows/emdash-release.yml。它不會推送檔案，除非你傳遞 --force，否則不會取代現有工作流程。

產生的工作流程在匹配 v* 的版本標籤和 workflow_dispatch 時執行。它授予 contents: read、id-token: write 和 attestations: write；將第三方 Actions 固定到完整的提交識別碼；建置一個外掛套件組合；為這些確切位元組建立 GitHub 建置來源；並將兩個檔案傳遞給 EmDash 發佈 Action。
開啟發佈服務儀表板並使用相同的 Atmosphere 帳戶登入。

選擇 Authorize publishing。你的帳戶提供者顯示確切的委託權限。保留的授權可以建立套件發佈記錄並上傳套件或列表圖片 Blob。它不能建立或編輯套件設定檔、更新或刪除發佈、或寫入其他集合。
建立工作流程邀請。

輸入 emdash-plugin.jsonc 中的外掛 ID，然後選擇 Create invitation。將一次性值作為名為 EMDASH_CONNECTION_INVITATION 的 Actions 密鑰新增到 GitHub 儲存庫。

邀請有效期為 30 分鐘，只能連接指定的外掛。如果在工作流程消費之前過期，請建立新的邀請。
啟動發佈工作流程。

在建立版本標籤之前更新套件版本。以下命令啟動 1.2.3 發佈：
```
git tag v1.2.3
git push origin v1.2.3
```
你也可以在儲存庫的 GitHub Actions 頁面選擇 Run workflow。
在首次執行時核准工作流程連接。

Action 在 GitHub 工作摘要中寫入連結並等待。開啟連結並確認外掛、儲存庫、工作流程檔案、分支或標籤和環境。

對於標籤觸發的執行，選擇 All version tags 或 Only this tag。分支觸發的請求僅涵蓋該分支。服務儲存 GitHub 儲存庫和擁有者 ID 以及所選的 ref 和環境範圍。後續執行必須匹配此策略。
需要時審批發佈。

擴展外掛權限的發佈，或設定為每次發佈確認的設定檔，進入 Awaiting approval 狀態。從 Action 輸出或發佈儀表板開啟審批 URL。如果審批帳戶還沒有通行金鑰，請註冊一個，審查權限變更，然後核准或拒絕發佈。

Action 的預設設定在發佈達到 Awaiting approval 時成功返回。服務工作流程繼續等待瀏覽器決定，在核准後發佈。

發佈服務驗證的內容

服務在寫入發佈之前完成以下檢查：

GitHub OpenID Connect（OIDC）權杖指定了經授權的儲存庫、擁有者、工作流程、ref、環境、提交、執行和 GitHub 託管執行器。
套件設定檔存在，由發佈者簽署，包含委託發佈設定，並指定相同的規範 GitHub 儲存庫。
請求的套件和版本與建置的外掛套件組合匹配。
套件校驗和與上傳的位元組匹配。
GitHub 來源涵蓋相同的套件組合、儲存庫、工作流程、提交和執行。
發佈記錄的宣告存取權限與套件組合清單匹配。
版本記錄尚不存在。
任何必需的通行金鑰審批涵蓋確切的驗證結果和當前設定檔修訂。

Action 為每次服務呼叫請求一個新的 GitHub OIDC 權杖。套件組合和來源檔案僅在工作流程被授權後進入私有暫存儲存。服務將經驗證的套件和圖片位元組上傳到發佈者的個人資料伺服器（PDS），在那裡建立發佈記錄，並透過不可變的校驗和定址 URL 公開經驗證的來源。

權限邊界

每個憑證都有一個職責：

憑證	使用者	權限
本地 CLI OAuth 工作階段	`emdash-plugin profile setup`	在本地確認後建立或更新發佈者擁有的套件設定檔。
GitHub OIDC 權杖	發佈 Action	向服務識別一次 GitHub 工作流程執行。不授予 AT Protocol 寫入存取權限。
發佈服務委託	發佈服務	建立套件發佈記錄並上傳所需的 Blob。
發佈者應用程式工作階段	發佈儀表板	授權工作流程連接和撤銷委託發佈。
審批者工作階段和通行金鑰	審批頁面	核准或拒絕一次校驗和繫結的發佈驗證。
Cloudflare Access 身分	服務營運控制台	營運託管服務。不代表發佈者或審批者。

服務分別儲存發佈者和審批者狀態。登入查看你的發佈不會授予營運存取權限，營運身分不能作為發佈者核准發佈。

Action 行為

產生的工作流程使用 apps/release-action 中的 Action。Action 接受建置的套件組合加上原始 Sigstore 來源，或包含校驗和繫結的 HTTPS 工件來源的相容性 release-file。不要將 release-file 與套件組合或來源輸入組合使用。

標準產生的工作流程提供以下輸入：

輸入	值
`service-url`	發佈服務 HTTPS 來源。
`publisher-did`	擁有套件設定檔和發佈的 DID。
`connection-invitation`	首次連接時的 `EMDASH_CONNECTION_INVITATION`。
`bundle-file`	`emdash-plugin bundle` 產生的單一 tarball。
`provenance-file`	`actions/attest-build-provenance` 的原始 `bundle-path` 輸出。

Action 返回以下輸出：

輸出	含義
`connection-url`	首次執行時工作流程審批的瀏覽器 URL。
`intent-id`	發佈意圖識別碼。
`state`	Published、終端或 `awaiting_approval` 狀態。
`approval-url`	需要通行金鑰審批時的瀏覽器 URL。
`release-uri`	已發佈發佈的 AT URI。
`release-cid`	已發佈發佈記錄的 CID。
`reason-code`	終端意圖的穩定原因。

有關選用輸入、自訂 URL 來源工作流程、輪詢控制和確切輸出行為，請參閱 Action 參考。

疑難排解

`PACKAGE_PROFILE_REQUIRED`

套件設定檔缺失、缺少委託發佈設定、使用非規範的儲存庫 URL，或指定了與 GitHub 工作流程不同的儲存庫。

使用發佈者帳戶在本地執行設定檔設定，然後重新啟動工作流程：

pnpm exec emdash-plugin profile setup

此檢查在服務接受套件組合或來源上傳之前執行。

需要公開儲存庫

GitHub 對私有和內部儲存庫使用私有 Sigstore 信任根。發佈驗證者目前僅信任公共 GitHub 來源。將發佈工作流程移到公開儲存庫，或使用 emdash-plugin publish 在本地發佈。

邀請已過期或無效

在發佈儀表板中建立另一個邀請並取代 EMDASH_CONNECTION_INVITATION。在 30 分鐘內啟動工作流程。邀請是一次性的，限定為一個外掛 ID。

`WORKLOAD_NOT_ALLOWED`

GitHub 儲存庫、擁有者、工作流程檔案、ref 或環境與已核准的工作流程策略不匹配。開啟發佈儀表板並使用預期的範圍核准新的工作流程連接。

`PROFILE_FETCH_FAILED`

服務無法從發佈者的 PDS 驗證設定檔。在帳戶提供者可用後重試。如果設定檔已被刪除或變更，執行 emdash-plugin profile setup。

`POLL_TIMEOUT`

Action 在工作流程審批、發佈審批或發佈完成之前達到了 timeout-minutes。在重新執行之前檢查發佈儀表板中的意圖狀態。相同 GitHub Actions 執行的重新執行會重用其冪等金鑰。

撤銷自動化發佈

在發佈儀表板中選擇 Turn off automated publishing。撤銷會清除保留的發佈委託。現有的套件設定檔、發佈、審核標籤、已安裝的外掛和儀表板登入不會改變。

在下次自動化發佈之前，重新連接發佈並再次核准工作流程。