設定管線和推送更新

發行項
09/13/2024

在本文中，您將瞭解如何使用 Azure 開發人員 CLI （azd）透過 CI/CD 管線推送範本變更，例如 GitHub Actions 或 Azure DevOps。在此範例中，您會在 Azure 範本上使用 React Web 應用程式搭配 Node.js API 和 MongoDB，但您可以將本文中學到的原則套用至任何 Azure 開發人員 CLI 範本。

注意

命令 azd pipeline config 仍在 Beta 中。在功能版本設定和發行策略頁面上深入瞭解 Alpha 和 Beta 功能支援。

必要條件

azd 範本不一定包含稱為的預設 GitHub Actions 和/或 Azure DevOps 管線組態檔 azure-dev.yml，這是設定 CI/CD 的必要專案。此組態檔會布建您的 Azure 資源，並將程式代碼部署至 main 分支。您可以找到 azure-dev.yml：

針對 GitHub Actions： 在 .github/workflows 目錄中。
針對 Azure DevOps： 在 .azdo/pipelines 目錄中。

您可以依目前使用組態檔，或修改它以符合您的需求。

注意

在呼叫 azd pipeline config之前，請確定您的範本具有管線定義（azure-dev.yaml）。 azd 不會自動建立此檔案。請參閱下方的 azd 建立管線定義。

azd pipeline config使用命令來設定 CI/CD 管線，以處理下列工作：

在 Azure 訂用帳戶上建立及設定應用程式的服務主體。您的用戶必須在 Azure 訂用帳戶內具有 Owner 角色或 Contributor + User Access Administrator 角色，才能允許 azd 建立角色，並將角色指派給服務主體。
逐步引導您完成工作流程，以建立和設定 GitHub 或 Azure DevOps 存放庫，並將專案程式代碼認可至該工作流程。您也可以選擇使用現有的存放庫。
建立 Azure 與存放庫之間的安全連線。
當您簽入工作流程檔案時，請執行 GitHub 動作。

若要更細微地控制此程式，或如果用戶沒有必要的角色，您可以手動設定管線。

選取您慣用的管線提供者以繼續：

GitHub 動作
Azure DevOps

授權 GitHub 部署至 Azure

若要設定工作流程，您必須授權服務主體從 GitHub 動作代表您部署至 Azure。 azd 會為其建立服務主體和同盟認證。

執行下列命令以建立 Azure 服務主體並設定管線：
```
azd pipeline config
```
此命令會選擇性地建立 GitHub 存放庫，並將程式代碼推送至新的存放庫。

注意

根據預設，azd pipeline config會使用稱為同盟認證的 OpenID Connect （OIDC）。如果您不想使用 OIDC，請執行 azd pipeline config --auth-type client-credentials。

Terraform 不支援 OIDC/同盟認證。

深入瞭解中的 azdOIDC 支援。
提供要求的 GitHub 資訊。
當系統提示您認可和推送本機變更以啟動新的 GitHub Actions 執行時，請指定 y。
在終端機視窗中，檢視命令的結果 azd pipeline config 。此命令 azd pipeline config 會輸出專案的 GitHub 存放庫名稱。
使用瀏覽器，開啟專案的 GitHub 存放庫。
選取 [ 動作 ] 以查看工作流程正在執行。

進行和推送程式代碼變更

在項目的 /src/web/src/layout 目錄中，開啟 header.tsx。
找出行 <Text variant="xLarge">ToDo</Text>。
將常值 ToDo 變更為 myTodo。
儲存檔案。
認可您的變更。認可變更會啟動 GitHub Action 管線來部署更新。
使用瀏覽器，開啟專案的 GitHub 存放庫，以查看這兩者：
- 您的認可
- 正在設定的 GitHub Actions 認可。
選取 [ 動作 ] 以查看工作流程中反映的測試更新。
請流覽 Web 前端 URL 以檢查更新。

`azd` 作為 GitHub 動作

新增 azd 為 GitHub 動作。此動作將會安裝 azd。若要使用它，您可以將下列內容新增至 .github\workflows\azure-dev.yml：

on: [push]

jobs:
   build:
      runs-on: ubuntu-latest
      steps:
         - name: Install azd
         uses: Azure/setup-azd@v0.1.0

注意

如果您在 Windows 上使用 Azure DevOps 進行 Java 範本，請參閱疑難解答指南中的對應一節。

建立或使用現有的 Azure DevOps 組織

若要在 Azure DevOps 中執行管線，您需要 Azure DevOps 組織。您可以使用 Azure DevOps 入口網站建立一個： https://dev.azure.com。

建立個人存取令牌

Azure 開發人員 CLI 依賴 Azure DevOps 個人存取令牌（PAT）來設定 Azure DevOps 專案。建立新的 Azure DevOps PAT。

建立 PAT 時，請設定下列範圍：

代理程式集區（讀取、管理）
建置（讀取並執行）
程式代碼（完整）
專案和小組（讀取、寫入和管理）
發行（讀取、寫入、執行和管理）
服務連線（讀取、查詢和管理）

叫用管線設定命令

（選擇性）若要將預設管線提供者從 GitHub Actions 更新至 Azure DevOps，請編輯 azure.yaml 位於您專案的根目錄，並新增下列專案：
```
pipeline: 
   provider: azdo 
```
執行下列命令，以使用部署管線設定 Azure DevOps 專案和存放庫。
```
azd pipeline config --provider azdo
```
如果您在步驟 1 中執行設定更新，可以省略 --provider 旗標：
```
azd pipeline config
```

注意

根據預設， azd pipeline config 在 Azure DevOps client-credentials中使用。 azd 目前不支援 Azure DevOps 的 OIDC/同盟認證。深入瞭解中的 azdOIDC 支援。

提供下列提示的解答：
- 個人存取權杖（PAT）
  - 複製/貼上您的 PAT。
  - 執行下列命令，將您的 PAT 匯出為系統環境。否則，每次設定 Azure Pipeline 時，都會提示您：
```
export AZURE_DEVOPS_EXT_PAT=<PAT>
```
- 請輸入 Azure DevOps 組織名稱：
  -輸入您的 AzDo 組織。按 Enter 鍵後， AZURE_DEVOPS_ORG_NAME="<your Azure DevOps Org Name>" 會自動新增至目前環境的 .env 檔案。
- 找不到名為「origin」的遠端。您要設定一個嗎？
  - Yes
- 您要如何設定專案？
  - 建立新的 Azure DevOps 專案
- 輸入新 Azure DevOps 項目名稱或點擊輸入以使用此名稱：（{預設名稱} ）
  - 選取 Enter，或建立唯一的項目名稱。
- 您要認可並推送本機變更以啟動已設定的 CI 管線嗎？
  - Yes
瀏覽至您的 Azure DevOps 入口網站（https://dev.azure.com）以尋找您的項目並確認組建。

進行和推送程式代碼變更

在項目的 /src/web/src/layout 目錄中，開啟 header.tsx。
找出行 <Text variant="xLarge">ToDo</Text>。
將常值 ToDo 變更為 myTodo。
儲存檔案。
建立分支並認可您的變更。 main Azure DevOps 中的分支會受到保護，以免直接推送。您必須從新的分支推送變更，並在 Azure DevOps 中建立 Pull Request 。提取要求會自動啟動管線，並在管線失敗時防止合併。
核准並合併提取要求，以再次啟動管線。
使用瀏覽器，開啟專案的存放庫以查看這兩者：
- 您的認可
- Azure Pipeline
請流覽 Web 前端 URL 以檢查更新。

`azd` 作為 Azure DevOps 工作

新增 azd 為 Azure DevOps 工作。這個工作將會安裝 azd。若要使用它，您可以將下列內容新增至 .azdo\pipelines\azure-dev.yml：

trigger:
   - main
   - branch

pool:
   vmImage: ubuntu-latest
   # vmImage: windows-latest

steps:
   - task: setup-azd@0
   displayName: Install azd

清除資源

當您不再需要本文中建立的 Azure 資源時，請執行下列命令：

azd down

進階功能

您可以擴充 azd pipeline config 特定範本案例或需求的命令，如下列各節所述。

其他秘密或變數

根據預設， azd 設定管線的變數和秘密。例如， azd pipeline config 命令會在 subscription id執行時建立和 environment name region 作為管線變數。然後管線定義會參考這些變數：

env:
   AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
   AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
   AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
   AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
   AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}

當管線執行時， azd 從環境取得值，其會對應至變數和秘密。視範本而定，可能會有您可以使用環境變數來控制的設定。例如，可以設定名為 KEY_VAULT_NAME 的環境變數，以定義範本基礎結構內金鑰保存庫資源的名稱。在這種情況下，範本可以使用來定義 azure.yaml變數和秘密的清單。例如，請考慮下列 azure.yaml 組態：

pipeline:
  variables:
    - KEY_VAULT_NAME
    - STORAGE_NAME
  secrets:
    - CONNECTION_STRING

使用此組態時， azd 檢查環境中是否有任何變數或秘密具有非空白值。 azd 然後，使用組態中的索引鍵名稱做為變數或秘密，以及來自環境的非字串值，建立管線的變數或秘密。

azure-dev.yaml然後管線定義可以參考變數或秘密：

- name: Provision Infrastructure
   run: azd provision --no-prompt
   env:
      KEY_VAULT_NAME: ${{ variables.KEY_VAULT_NAME }}
      STORAGE_NAME: ${{ variables.STORAGE_NAME }}
      CONNECTION_STRING: ${{ secrets.CONNECTION_STRING }}

注意

您必須在中更新秘密azure.yaml或變數清單之後執行azd pipeline config，azd 才能重設管線值。

基礎結構參數

請考慮下列 bicep 範例：

@secure()
param BlobStorageConnection string

參數 BlobStorageConnection 未設定預設值，因此 azd 會提示使用者輸入值。不過，CI/CD 期間沒有互動式提示。 azd 當您執行 azd pipeline config時，必須要求參數的值、將值儲存在管線中，然後在管線執行時再次擷取值。

azd 會使用稱為 AZD_INITIAL_ENVIRONMENT_CONFIG 的管線秘密，自動儲存並設定管線中所有必要參數的值。您只需要在管線中參考此秘密：

- name: Provision Infrastructure
   run: azd provision --no-prompt
   env:
      AZD_INITIAL_ENVIRONMENT_CONFIG: ${{ secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}

當管線執行時， azd 會從秘密取得參數的值，以移除互動式提示的需求。

注意

如果您新增參數，則必須重新執行 azd pipeline config 。

建立管線定義

azd如果您的範本還沒有 CI/CD 管線定義檔案，您可以自行建立一個檔案。 CI/CD 管線定義通常有 4 個主要區段：

觸發程序 (trigger)
權限
操作系統或集區
要執行的步驟

下列範例示範如何建立 GitHub Actions 和 Azure Pipelines 的定義檔和相關組態。

GitHub 動作
Azure DevOps

在 GitHub Actions 中執行 azd 需要下列設定：

授 id-token: write 與和 contents: read 存取範圍。
除非您使用已安裝的 azd docker 映像，否則請安裝 azd 巨集指令。

您可以使用下列樣本作為您自己的管線定義的起點：

on:
  workflow_dispatch:
  push:
    # Run when commits are pushed to mainline branch (main or master)
    # Set this to the mainline branch you are using
    branches:
      - main
      - master

# Set this permission if you are using a Federated Credential.
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    # azd build-in variables.
    # This variables are always set by `azd pipeline config`
    # You can set them as global env (apply to all steps) or you can add them to individual steps' environment
    env:
      AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
      AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
      AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
      ## Define the additional variables or secrets that are required globally (provision and deploy)
      # ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
      # ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}      
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # using the install-azd action
      - name: Install azd
        uses: Azure/setup-azd@v1.0.0

      # # If you want to use azd-daily build, or install it from a PR, you can remove previous step and
      # # use the next one:
      # - name: Install azd - daily or from PR
      #  # Update this scrip based on the OS - pool of your pipeline. This example is for a linux pipeline installing daily build
      #  run: curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --version daily
      #  shell: pwsh

      # azd set up Federated Credential by default. You can remove this step if you are using Client Credentials
      - name: Log in with Azure (Federated Credentials)
        if: ${{ env.AZURE_CLIENT_ID != '' }}
        run: |
          azd auth login `
            --client-id "$Env:AZURE_CLIENT_ID" `
            --federated-credential-provider "github" `
            --tenant-id "$Env:AZURE_TENANT_ID"
        shell: pwsh

      ## If you set up your pipeline with Client Credentials, remove previous step and uncomment this one
      # - name: Log in with Azure (Client Credentials)
      #   if: ${{ env.AZURE_CREDENTIALS != '' }}
      #   run: |
      #     $info = $Env:AZURE_CREDENTIALS | ConvertFrom-Json -AsHashtable;
      #     Write-Host "::add-mask::$($info.clientSecret)"

      #     azd auth login `
      #       --client-id "$($info.clientId)" `
      #       --client-secret "$($info.clientSecret)" `
      #       --tenant-id "$($info.tenantId)"
      #   shell: pwsh
      #   env:
      #     AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Provision Infrastructure
        run: azd provision --no-prompt
        env:
         #  # uncomment this if you are using infrastructure parameters
         #  AZD_INITIAL_ENVIRONMENT_CONFIG: ${{ secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}
         ## Define the additional variables or secrets that are required only for provision 
         #  ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
         #  ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}

      - name: Deploy Application
        run: azd deploy --no-prompt
        env:
         ## Define the additional variables or secrets that are required only for deploy
         #  ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
         #  ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}

您可以使用下列樣本作為您自己的管線定義的起點：

# Run when commits are pushed to mainline branch (main or master)
# Set this to the mainline branch you are using
trigger:
  - main
  - master

pool:
  vmImage: ubuntu-latest

steps:
  - task: setup-azd@0 
    displayName: Install azd

  # If you can't use above task in your organization, you can remove it and uncomment below task to install azd
  # The script can be changed to use azd-daily build or build from PR
#   - task: Bash@3
#     displayName: Install azd
#     inputs:
#       targetType: 'inline'
#       script: |
#         curl -fsSL https://aka.ms/install-azd.sh | bash

  # azd delegate auth to az to use service connection with AzureCLI@2
  - pwsh: |
      azd config set auth.useAzCliAuth "true"
    displayName: Configure AZD to Use AZ CLI Authentication.

   - task: AzureCLI@2
      displayName: Provision Infrastructure
      inputs:
         # azconnection is created by azd pipeline config
         azureSubscription: azconnection
         scriptType: bash
         scriptLocation: inlineScript
         inlineScript: |
         azd provision --no-prompt
      env:
         # azd build-in variables.
         AZURE_SUBSCRIPTION_ID: $(AZURE_SUBSCRIPTION_ID)
         AZURE_ENV_NAME: $(AZURE_ENV_NAME)
         AZURE_LOCATION: $(AZURE_LOCATION)
         # # uncomment this if you are using infrastructure parameters
         # AZD_INITIAL_ENVIRONMENT_CONFIG: ${{ secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}
         # # Define the additional variables or secrets that are required only for provision 
         # ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
         # ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}

   - task: AzureCLI@2
      displayName: Deploy Application
      inputs:
         azureSubscription: azconnection
         scriptType: bash
         scriptLocation: inlineScript
         inlineScript: |
         azd deploy --no-prompt
      env:
         # azd build-in variables.
         AZURE_SUBSCRIPTION_ID: $(AZURE_SUBSCRIPTION_ID)
         AZURE_ENV_NAME: $(AZURE_ENV_NAME)
         AZURE_LOCATION: $(AZURE_LOCATION)
         # # Define the additional variables or secrets that are required only for deploy 
         # ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
         # ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}

要求說明

如需如何提出 Bug、要求協助或為 Azure 開發人員 CLI 提出新功能的資訊，請流覽疑難解答和支援頁面。

下一步

使用 Azure 開發人員 CLI 監控您的應用程式（azd）

共用方式為

設定管線和推送更新

必要條件

授權 GitHub 部署至 Azure

進行和推送程式代碼變更

`azd` 作為 GitHub 動作

建立或使用現有的 Azure DevOps 組織

建立個人存取令牌

叫用管線設定命令

進行和推送程式代碼變更

`azd` 作為 Azure DevOps 工作

清除資源

進階功能

其他秘密或變數

基礎結構參數

建立管線定義

要求說明

下一步

意見反應

其他資源

共用方式為

設定管線和推送更新

必要條件

授權 GitHub 部署至 Azure

進行和推送程式代碼變更

azd 作為 GitHub 動作

清除資源

進階功能

其他秘密或變數

基礎結構參數

建立管線定義

意見反應

其他資源

`azd` 作為 GitHub 動作