以下章節將介紹 Microsoft Power Platform 的 GitHub Actions。 這些章節也展示了 GitHub 工作流程範例。 欲了解更多關於 GitHub Actions 及其下載方式,請參閱 Microsoft Power Platform 的 GitHub Actions。
設定可與 GitHub Actions 搭配使用的 Microsoft Power Platform 認證
許多動作都需要您連接到 Microsoft Dataverse 環境。 在你的 GitHub 倉庫中將服務主體或使用者憑證作為 Secrets,然後在工作流程中使用它們。
如需如何在 GitHub 中設定秘密的詳細資訊,請參閱「加密的秘密」。
關於如何為 Microsoft Power Platform 設定服務主體認證的詳細資訊,請參閱 DevOps Build 工具。
設定好憑證後,你可以在 Action 腳本中呼叫服務主體。
在你的 GitHub Actions 指令碼中將以下參數定義為環境變數:
- 應用程式識別碼,例如:
WF_APPLICATION_ID:<your application id> - 租戶識別,例如:
WF_TENANT_ID:<your tenant id>
將 client secret 新增為 GitHub secret。 在工作流程中,使用類似以下參數來參考: client secret: ${{secrets.CLIENT_SECRET_GITHUB_ACTIONS}}
協助程式工作
可使用下列協助程式工作。
actions-install
當GitHub Actions工作流程強制在執行器情境下安裝 Power Platform CLI 並發生逾時錯誤時,請使用 version 1(@v1)並附加額外動作(actions-install),如以下範例所示。
重要
- 使用第 1 版 (@v1) 可能會導致現有的 GitHub 動作更新,進而使目前的工作流程跟著更新。
- 將 Install Power Platform Tools 工作新增為工作流程中的第一個工作,放在任何其他適用於 Power Platform 的 GitHub Actions 之前。
jobs:
builds:
runs-on: windows-latest # alternate runner OS is: ubuntu-latest
steps:
- name: Install Power Platform Tools
uses: microsoft/powerplatform-actions/actions-install@v1
- name: Export Solution
uses: microsoft/powerplatform-actions/export-solution@v1
with:
environment-url: 'https://myenv.crm.dynamics.com'
user-name: 'me@myenv.onmicrosoft.com'
password-secret: ${{ secrets.MYPASSWORD }}
solution-name: aSolution
solution-output-file: 'aSolution.zip'
working-directory: 'out'
你可以在 Power Platform Actions 找到更多 GitHub Actions 範例。
whoAmI
藉由連接服務及傳送 WhoAmI [SDK/Web API] 請求核驗服務連接。 將這個任務提早加入 GitHub 工作流程中,有助於在處理開始前驗證連線性。
| 參數 | 描述 |
|---|---|
| environment-url | 您要連線到的環境 URL。 |
| 使用者名稱 | 用來連線的帳戶使用者名稱。 |
| password-secret | 用於 user-name 的密碼。 在「設定」的「秘密」下定義 GitHub 密碼。 你無法在定義並儲存秘密後再取回它。 |
| 應用程式識別碼 | 用於驗證的應用程式識別碼。 使用服務主體認證進行驗證時需要此參數。 |
| client-secret | 用於驗證 GitHub 管線的用戶端密鑰。 使用服務主體認證進行驗證時需要此參數。 |
| tenant-id | 使用 app-id 和 client-secret 驗證認證時的租用戶識別碼。 |
解決方案工作
這些工作會對解決方案執行動作,包括下列各項。
匯入解決方案
將解決方案匯入至目標環境。
| 參數 | 描述 |
|---|---|
| environment-url | (必要) 您想要將解決方案匯入其中的目標環境 URL (例如 https://YourOrg.crm.dynamics.com)。 |
| 使用者名稱 | (必要) 如果您採用使用者名稱/密碼驗證,此為您用來連線的帳戶使用者名稱。 |
| password-secret | (必要) 如果您採用使用者名稱/密碼驗證,此為您用來連線的帳戶密碼。 |
| solution-file | (必要) 您要匯入之解決方案檔案的路徑與名稱。 |
| 應用程式識別碼 | 用於驗證的應用程式識別碼。 使用服務主體認證進行驗證時,此參數為必填。 |
| client-secret | 用於驗證 GitHub 管線的用戶端密鑰。 使用服務主體認證進行驗證時,此參數為必要。 |
| tenant-id | 使用 app-id 和 client-secret 進行驗證時的租用戶識別碼。 |
匯出解決方案
從來源環境中匯出解決方案。
| 參數 | 描述 |
|---|---|
| 環境-網址 | (必要) 您要從中匯出解決方案的環境 URL (例如:https://YourOrg.crm.dynamics.com)。 |
| 使用者名稱 | (必要) 如果您使用使用者名稱/密碼驗證,請輸入用於連線之帳戶的使用者名稱。 |
| password-secret | (必要) 如果您採用使用者名稱/密碼驗證,此為 user-name 的密碼。 在「設定」的「秘密」下定義 GitHub 密碼。 你無法在定義並儲存秘密後再取回它。 |
| app-id | 用於驗證的應用程式識別碼。 使用服務主體認證進行驗證時,此參數為必要。 |
| client-secret | 用來驗證 GitHub 管線的用戶端密碼。 使用服務主體認證進行驗證時,此參數為必填。 |
| 租用戶識別碼 | 使用 app-id 和 client-secret 驗證時的租用戶識別碼。 |
| solution-name | (必要) 要匯出的解決方案名稱。 請務必使用解決方案的名稱,而不是顯示名稱。 |
| 解決方案輸出檔案 | (必要) 要匯出來源環境至的 solution.zip 檔案路徑和名稱。 |
| Managed | (必要) 設定為 true 以匯出為受管理的解決方案;預設值 (false) 會匯出為未受管理的解解決方案。 |
unpack-solution
將壓縮好的解決方案檔案分解成多個 XML 檔案。 你可以更輕鬆地在原始碼控制系統中讀取和管理這些檔案。
| 參數 | 描述 |
|---|---|
| solution-file | (必要) 要解除封裝的 solution.zip 檔案的路徑及檔案名稱。 |
| 解決方案資料夾 | (必要) 要解除封裝解決方案的路徑和目標資料夾。 |
| 解決方案類型 | (必要) 要解除封裝的解決方案類型。 選項包括:未管理 (建議)、受管理和兩者。 |
pack-solution
它會將儲存在原始碼控制中的解決方案打包成可匯入其他環境的 solution.zip 檔案。
| 參數 | 描述 |
|---|---|
| solution-file | (必要) 要封裝成的 solution.zip 檔案路徑和檔名 (例如 out/CI/ALMLab.zip)。 |
| 解決方案資料夾 | (必要) 要封裝的解決方案的路徑及來源資料夾。 |
| 解決方案類型 | (可選) 要封裝的解決方案類型。 選項包括「Unmanaged」(建議使用)、「Managed」和「Both」。 |
publish-solution
發佈解決方案自訂項目。
| 參數 | 描述 |
|---|---|
| environment-url | (必要) 您想將方案發佈到其中的環境 URL (例如 https://YourOrg.crm.dynamics.com)。 |
| 使用者名稱 | (必要) 如果您使用的是使用者名稱/密碼驗證,請輸入用來連線的帳戶使用者名稱。 |
| password-secret | (必要) 如果您採用使用者名稱/密碼驗證,此為您用來連線的帳戶密碼。 |
| solution-file | (必要) 您要匯入之解決方案檔案的路徑與名稱。 |
| 應用程式識別碼 | 用於驗證的應用程式識別碼。 使用服務主體認證進行驗證時需要此參數。 |
| client-secret | 用來驗證 GitHub 管線的用戶端密碼。 使用服務主體認證進行驗證時需要此參數。 |
| 租戶識別碼 | 使用 app-id 和 client-secret 進行驗證時的租用戶 ID。 |
clone-solution
複製指定環境的解決方案。
| 參數 | 描述 |
|---|---|
| environment-url | (必要) 您想要從中複製解決方案的環境 URL (例如:https://YourOrg.crm.dynamics.com)。 |
| 使用者名稱 | (必要) 如果您使用的是使用者名稱/密碼驗證,請輸入用來連線的帳戶使用者名稱。 |
| password-secret | (必要) 如果您採用使用者名稱/密碼驗證,此為您用來連線的帳戶密碼。 |
| solution-file | (必要) 您要匯入之解決方案檔案的路徑與名稱。 |
| 應用程式識別碼 | 用於驗證的應用程式識別碼。 使用服務主體認證進行驗證時需要此參數。 |
| client-secret | 用於驗證 GitHub 管線的用戶端密鑰。 使用服務主體認證進行驗證時需要此參數。 |
| tenant-id | 使用 app-id 和 client-secret 驗證認證時的租用戶識別碼。 |
| solution-name | (必要) 要複製的 solution.zip 檔案路徑和名稱 (例如 out/CI/ALMLab.zip)。 |
| 解決方案版本 | 要複製的解決方案版本。 |
| 目標資料夾 | 用來放置擷取出的解決方案的目標資料夾。 (例如 Git 存放庫\target-solution-folder)。 |
| Working-directory | 暫存資料夾,用來存放複製解決方案所需的進行中成品。 預設: root of the repository |
check-solution
檢查解決方案檔案以偵測不一致。
| 參數 | 描述 |
|---|---|
| environment-url | (必要) 您想要從中複製解決方案的環境 URL (例如:https://YourOrg.crm.dynamics.com)。 |
| 使用者名稱 | (必要) 如果您使用的是使用者名稱/密碼驗證,請輸入用來連線的帳戶使用者名稱。 |
| password-secret | (必要) 如果您採用使用者名稱/密碼驗證,此為您用來連線的帳戶密碼。 |
| app-id | 用於驗證的應用程式識別碼。 使用服務主體認證進行驗證時需要此參數。 |
| client-secret | 用來驗證 GitHub 管線的用戶端密碼。 使用服務主體認證進行驗證時需要此參數。 |
| 租用戶識別碼 | 使用 app-id 和 client-secret 驗證認證時的租用戶識別碼。 |
| 路徑 | (必要) 您要檢查之解決方案檔案的路徑與名稱。 |
| 地區 | 使用哪一個 Microsoft Power Platform 檢查器服務的地理位置。 預設值為「united states」。 |
| 規則層級覆寫 | 檔案路徑,該檔案包含規則與規則層級的 JSON 陣列。 可接受的值為:Critical、High、Low 和 Informational。 範例:[{"Id":"meta-remove-dup-reg","OverrideLevel":"Medium"},{"Id":"il-avoid-specialized-update-ops","OverrideLevel":"Medium"}] |
| checker-logs-artifact-name | Microsoft Power Platform 檢查程式記錄要上傳到的成品資料夾名稱。 預設值為 'CheckSolutionLogs'。 |
upgrade-solution
升級解決方案。
| 參數 | 描述 |
|---|---|
| environment-url | (必要) 您想要從中複製解決方案的環境 URL (例如:https://YourOrg.crm.dynamics.com)。 |
| 使用者名稱 | (必要) 如果您使用的是使用者名稱/密碼驗證,請輸入您用來連線之帳戶的使用者名稱。 |
| password-secret | (必要) 如果您採用使用者名稱/密碼驗證,此為您用來連線的帳戶密碼。 |
| solution-file | (必要) 您要匯入之解決方案檔案的路徑與名稱。 |
| 應用程式識別碼 | 用於驗證的應用程式識別碼。 使用 Service Principal 認證資訊進行驗證時,需要此參數。 |
| client-secret | 用來驗證 GitHub 管線的用戶端密碼。 使用服務主體認證進行驗證時需要此參數。 |
| 租用戶識別碼 | 使用 app-id 和 client-secret 驗證認證時的租用戶識別碼。 |
| solution-name | (必要) 要升級之解決方案的名稱。 |
| 非同步 | 以非同步方式升級解決方案。 |
| 最大非同步等候時間 | 最大非同步等待時間 (分鐘)。 預設值為 60 分鐘。 |
套件工作
這些任務會對套件執行動作。
部署套件
部署一個套件 DLL 或一個包含套件的 ZIP 檔案。
注意
此動作僅支援 Windows。
| 參數 | 描述 |
|---|---|
| environment-url | (必要) 您想要從中複製解決方案的環境 URL (例如:https://YourOrg.crm.dynamics.com)。 |
| 使用者名稱 | (必要) 如果您使用的是使用者名稱/密碼驗證,請輸入用來連線的帳戶使用者名稱。 |
| password-secret | (必填)如果您使用使用者名稱/密碼驗證,請輸入用來連線的帳戶密碼。 |
| 應用程式識別碼 | 用於驗證身分的應用程式識別碼。 使用服務主體認證進行驗證時需要此參數。 |
| client-secret | 用於驗證 GitHub 管線的用戶端密鑰。 使用服務主體認證進行驗證時,此參數為必要。 |
| tenant-id | 使用 app-id 和 client-secret 驗證認證時的租用戶識別碼。 |
| 套件 | (必要) 套件 DLL 或含有套件的 ZIP 檔案路徑。 |
入口網站工作
這些工作會針對 Power Pages 執行以下動作。
upload-paportal
上傳資料至 Power Pages。
| 參數 | 描述 |
|---|---|
| environment-url | (必要) 您要將解決方案匯入其中的環境 URL (例如 https://YourOrg.crm.dynamics.com)。 |
| 應用程式識別碼 | 用於驗證的應用程式識別碼。 使用服務主體認證進行驗證時需要此參數。 |
| client-secret | 用來驗證 GitHub 管線的用戶端密碼。 使用服務主體認證進行驗證時,此參數為必要。 |
| 租戶識別碼 | 使用 app-id 和 client-secret 進行驗證時的租用戶 ID。 |
| upload-path | 儲存網站內容的路徑 (alias: -p)。 |
| deployment-profile | 上傳入口網站資料,並使用 deployment-profiles/[profile-name].deployment.yaml 檔案中透過設定檔變數定義的環境詳細資料。 |
| 模型版本 | 表示待上傳的網站資料是否使用標準(1)或增強資料模型(2)。 預設值為 1。 |
深入了解 Microsoft Power Platform CLI 對 Power Pages 的支援
目錄工作 (預覽版)
這些任務會在 Power Platform 中執行目錄操作。
注意
目前,Power Platform 的目錄任務仍處於預覽階段。
安裝
將 Catalog 項目安裝到目標環境。
| 參數 | 描述 |
|---|---|
| catalog-item-id | (必要) 要安裝在目標環境上的目錄項目。 |
| target-url | (必要) 安裝目錄項目的目標環境 URL (例如 https://YourOrg.crm.dynamics.com)。 |
| 設定 | (必要) 供安裝架構執行的執行階段套件設定。 字串格式必須為 key=value|key=value。 |
| target-version | 要安裝的目標版本。 如果未指定版本,系統會選取已發佈的版本。 |
| poll-status | 輪詢以檢查要求的狀態。 |
提交
列出目前 Dataverse 環境 (組織) 中所有已發行的目錄項目。
| 參數 | 描述 |
|---|---|
| 路徑 | (必要) 目錄提交文件的路徑。 |
| package-zip | 套件 zip 檔案的路徑。 |
| solution-zip | 解決方案 zip 檔案的路徑。 |
| poll-status | 輪詢以檢查要求狀態。 |
狀態
取得目錄安裝或提交要求的狀態。
| 參數 | 描述 |
|---|---|
| tracking-id | (必要) 要求追蹤識別碼。 |
| 型別 | (必填)請求類型。 有效值為 Install 和 Submit。 |
GitHub 工作流程撰寫
想了解如何使用 GitHub Actions 撰寫 GitHub 工作流程,請完成 Microsoft Power Platform 的 GitHub Actions 實驗室。
欲了解更多資訊,請參閱關於 GitHub Actions。