發佈自訂的 GitHub 動作

  • 6 分鐘

您將在此了解如何為動作選擇正確的可見度、記錄及設定動作版本的最佳做法，以及如何將動作發佈至 GitHub Marketplace。

選擇動作的位置

顯示公用或私人動作此兩種可見度選項的影像之圖表。

建立動作時，首先必須決定您想要讓該動作上線的位置，以及該動作的可見度為 public 或 private。 動作的可見度決定設定動作版本所需建議和需求。 讓我們進一步了解這兩個可見度選項。

公開

任何存放庫中的工作流程都可以使用公用動作。 如果您想要開發的動作是讓它成為開放原始碼，或使其透過 GitHub Marketplace 以公開提供，則建議您在大多數情況下，必須讓動作有自己的存放庫，而不是和其他應用程式程式碼統合在一起。 如此一來，您即可像對待任何其他軟體內容一樣，設定動作版本、追蹤和設定版次。 這方便 GitHub 社群探索該動作，縮小程式代碼基底的範圍，供開發人員修正問題及擴充動作，並隔開動作和其他應用程式程式碼的版本控制。

私用

當動作位在私人存放庫時，只有處於同一存放庫的工作流程能夠使用該動作。 私人動作的檔案可以儲存在您存放庫的任何位置。 如果您打算將動作、工作流程和應用程式程式碼合併在單一存放庫中，建議您將動作儲存在 .github 目錄。 例如，.github/actions/action-a 與 .github/actions/action-b。

記錄動作

使用新的工具或應用程式時，如果文件說明模糊不清甚至遺失，都很令人沮喪。 無論您打算將動作設為公用或私人，請務必提供良好的動作說明文件，以方便其他人查看其運作方式。 第一件事就是為動作建立一個良好的 README.md 檔案。

開發人員通常會先在 README.md 檔案中查看動作的運作方式。 這是包含動作所有重要資訊的絕佳位置。 以下是要包含的未詳盡事項清單：

  • 詳細描述動作的功用
  • 必要的輸入和輸出引數
  • 選擇性的輸入和輸出引數
  • 動作使用的祕密
  • 動作使用的環境變數
  • 在工作流程中使用動作的範例

README.md 檔案通常應該包含使用者使用該動作時，應該知道的所有內容。 只要您認為是有用的資訊，都可以包含在 README.md 中。

動作的版次和版本

如果您要開發供其他人使用的動作，無論其為公用或私人，您都應該定義版本管理策略，以控制散發更新的方式。 主要的版本更新，包括影響合規性的必要重大修正和安全性修補程式，都必須清楚記載。

版次和版本管理的最佳做法

良好的版本管理策略應該包含版本控制建議。 使用者不應該將該動作的動作預設分支當作可能包含最新程式碼的預設分支參考，因為後者可能不夠穩定，以免導致工作流程中斷。 相反地，我們建議使用者在使用動作時應指定主要版本，並在發生問題時只導向至更特定的版本。 只要設定其 GitHub Actions 工作流程將目標設為標籤、認可的 SHA 或針對版本命名的特定分支，即可完成。 讓我們仔細看看這些版本選項。

標籤

標籤是管理動作版本的好方法。 使用標籤，使用者即可輕鬆區別主要和次要版本。 以下是建立版本時要考慮的實用做法清單：

  • 先建立及驗證版本分支的版次 (例如 release/v1)，再建立版本標籤 (例如 v1.0.2)。
  • 使用語意版本設定。
  • 移動主要版本控制標籤 (例如 v1、v2)，指向目前版本的 Git 參考。
  • 針對會中斷現有工作流程的變更，引入新的主要版本標籤 (v2)。
  • 發行具有 Beta 標籤的主要版本，以指出其狀態，例如 v2-beta。 當版本準備就緒後，您即可移除 -beta 標籤。

以下是各個選項的一些範例。

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

使用認可的 SHA

標籤很有用且被廣泛使用，但標籤的缺點是可刪除或移動。 使用 Git 時，每個認可都會收到計算的 SHA 值，這是唯一且無法修改的值。 使用認可 SHA 進行版本控制，能讓您以最安全可靠的方式設定版本並使用動作。 不過，通常在 Git 中可以將 SHA 雜湊縮寫為前幾個字元，Git 會識別此參考。 如果使用認可的 SHA 進行版本管理，您就必須使用完整的 SHA 值，而不是縮寫值。

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

將動作發佈至 GitHub Marketplace

顯示 GitHub Marketplace 的精描圖，這是用來建立及改善工作流程的工具。

當準備好要與 GitHub 社群共用動作時，您可以將其發佈至 GitHub Marketplace，向數百萬名 GitHub 使用者公開。 如果符合所有需求，系統會立即發佈已發佈到 GitHub Marketplace 的動作。 不符合需求的動作必須在發佈之前交由 GitHub 檢閱。 您必須確保存放庫只包含動作所需的中繼資料檔案、程式碼和檔案。 為動作建立單一存放庫，可讓您只用一個單位標記、發行和封裝程式碼。 GitHub 也會在 GitHub Marketplace 頁面中使用該動作的中繼資料。

以下是將動作發佈至 GitHub Marketplace 的要求。 適用於 Docker 容器動作和 JavaScript 動作：

  • 動作必須放在公用存放庫中。
  • 每個存放庫都必須包含單一動作。
  • 動作的中繼資料檔案 (action.yml 或 action.yaml) 檔案必須放在存放庫根目錄中。
  • 動作中繼資料檔案中的 name 在 GitHub Marketplace 中必須是唯一。
    • 名稱不能沿用 GitHub 的使用者或組織名稱，除非該使用者或該組織擁有者是動作發佈者。 例如，只有 GitHub 組織可以發佈名為 github 的動作。
    • name 不能沿用現有的 GitHub Marketplace 類別。
    • name 不能沿用現有的 GitHub 功能。

您可以將已建立的動作標記為新版本後發佈，藉以新增至 GitHub Marketplace。 GitHub 有幾個引導式步驟可讓您發佈動作的版本。 如需這些步驟的詳細資訊，請參閱本課程模組結尾的總結一節。