快速入门：使用 GitHub Actions 部署 Bicep 文件

项目
10/09/2024

GitHub Actions 是 GitHub 中用于自动执行软件开发工作流的一套功能。在本快速入门中，你将使用 GitHub Actions 部署 Azure 资源管理器，以自动将 Bicep 文件部署到 Azure。

本快速入门简要介绍了 GitHub Actions 和 Bicep 文件。若要了解设置 GitHub Actions 和项目的更详细步骤，请参阅使用 Bicep 和 GitHub Actions 部署 Azure 资源。

先决条件

具有活动订阅的 Azure 帐户。创建试用版订阅。
一个 GitHub 帐户。如果没有该帐户，请注册免费版。
一个 GitHub 存储库，用于存储 Bicep 文件和工作流文件。若要创建一个存储库，请参阅创建新存储库。

创建资源组

创建资源组。稍后在本快速入门中，你要将 Bicep 文件部署到此资源组。

CLI
PowerShell

az group create -n exampleRG -l chinanorth3

New-AzResourceGroup -Name exampleRG -Location chinanorth3

GitHub Actions 将在某个标识下运行。使用 az ad sp create-for-rbac 命令为标识创建服务主体。为服务主体授予在上一会话中创建的资源组的参与者角色，以便具有该标识的 GitHub 操作可以在此资源组中创建资源。建议授予所需的最低访问权限。

az ad sp create-for-rbac --name {app-name} --role contributor --scopes /subscriptions/{subscription-id}/resourceGroups/exampleRG --json-auth

请将 {app-name} 占位符替换为应用程序的名称。将 {subscription-id} 替换为订阅 ID。

输出是一个 JSON 对象，其中包含的角色分配凭据可提供对应用服务应用的访问权限，类似于以下输出。

  {
    "clientId": "<GUID>",
    "clientSecret": "<GUID>",
    "subscriptionId": "<GUID>",
    "tenantId": "<GUID>",
    ...
  }

复制此 JSON 对象供以后使用。只需具有 clientId、clientSecret、subscriptionId 和 tenantId 值的部分。确保最后一行末尾没有额外的逗号，例如上一个示例中的 tenantId 行，否则将导致 JSON 文件无效。部署过程中会出现错误，指出“登录失败并出现错误: 内容不是有效的 JSON 对象。请仔细检查‘auth-type’是否正确。”

Open ID Connect 是一种使用短期令牌的身份验证方法。使用 GitHub Actions 设置 OpenID Connect 的过程会更复杂，能提供更强的安全性。

如果没有现有的应用程序，请注册一个可访问资源的新 Active Directory 应用程序和服务主体。创建 Active Directory 应用程序。
```
az ad app create --display-name myApp
```
此命令将输出 JSON，其中 appId 是你的 client-id。保存该值，稍后将其用作 AZURE_CLIENT_ID GitHub 机密。

使用图形 API 创建联合凭据时，将使用 objectId 值，并将其引用为 APPLICATION-OBJECT-ID。
创建服务主体。将 $appID 替换为 JSON 输出中的 appId。

此命令使用不同的 objectId 生成 JSON 输出，将在下一步中使用。新的 objectId 是 assignee-object-id。

复制 appOwnerTenantId 以在稍后用作 AZURE_TENANT_ID 的 GitHub 机密。
```
 az ad sp create --id $appId
```
按订阅和对象创建新的角色分配。默认情况下，角色分配将绑定到默认订阅。将 $subscriptionId 替换为你的订阅 ID，将 $resourceGroupName 替换为你的资源组名称，将 $assigneeObjectId 替换为生成的 assignee-object-id。了解如何使用 Azure CLI 管理 Azure 订阅。
```
az role assignment create --role contributor --subscription $subscriptionId --assignee-object-id  $assigneeObjectId --assignee-principal-type ServicePrincipal --scopes /subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.Web/sites/
```
运行以下命令，为 Active Directory 应用程序创建新的联合标识凭据。
- 将 APPLICATION-OBJECT-ID 替换为 Active Directory 应用程序的 objectId（在创建应用时生成）。
- 为 CREDENTIAL-NAME 设置一个值供以后引用。
- 设置 subject。此项的值由 GitHub 根据工作流定义：
  - GitHub Actions 环境中的作业：repo:< Organization/Repository >:environment:< Name >
  - 对于未绑定到环境的作业，请根据用于触发工作流的 ref 路径包括分支/标记的 ref 路径：repo:< Organization/Repository >:ref:< ref path>。例如 repo:n-username/ node_express:ref:refs/heads/my-branch 或 repo:n-username/ node_express:ref:refs/tags/my-tag。
  - 对于由拉取请求事件触发的工作流：repo:< Organization/Repository >:pull_request。
```
az rest --method POST --uri 'https://microsoftgraph.chinacloudapi.cn/beta/applications/<APPLICATION-OBJECT-ID>/federatedIdentityCredentials' --body '{"name":"<CREDENTIAL-NAME>","issuer":"https://token.actions.githubusercontent.com","subject":"repo:organization/repository:ref:refs/heads/main","description":"Testing","audiences":["api://AzureADTokenExchange"]}'
```

配置 GitHub 机密

服务主体
Open ID Connect

为 Azure 凭据、资源组和订阅创建机密。将在创建工作流部分使用这些机密。

在 GitHub 中导航到你的存储库。
选择“设置”>“机密和变量”>“操作”>“新建存储库机密”。
将 Azure CLI 命令的整个 JSON 输出粘贴到机密的值字段中。将机密命名为 AZURE_CREDENTIALS。
创建另一个名为 AZURE_RG 的机密。将资源组的名称添加到机密的值字段 (exampleRG)。
创建另一个名为 AZURE_SUBSCRIPTION 的机密。将订阅 ID 添加到该机密的“值”字段（例如：90fd3f9d-4c61-432d-99ba-1273f236afa2）。

需要向登录操作提供应用程序的“客户端 ID”、“租户 ID”和“订阅 ID”。这些值可直接在工作流中提供，或可存储在 GitHub 机密中并在工作流中引用。将这些值保存为 GitHub 机密是更安全的选择。

打开 GitHub 存储库并转到“设置”。
选择“设置”>“机密”>“新建机密”。
为 AZURE_CLIENT_ID、AZURE_TENANT_ID 和 AZURE_SUBSCRIPTION_ID 创建机密。将 Active Directory 应用程序中的这些值用于 GitHub 机密：

GitHub 机密 Active Directory 应用程序

AZURE_CLIENT_ID 应用程序（客户端）ID

AZURE_TENANT_ID 目录（租户）ID

AZURE_SUBSCRIPTION_ID 订阅 ID
通过选择“添加机密”来保存每个机密。

GitHub 机密	Active Directory 应用程序
AZURE_CLIENT_ID	应用程序（客户端）ID
AZURE_TENANT_ID	目录（租户）ID
AZURE_SUBSCRIPTION_ID	订阅 ID

添加 Bicep 文件

将 Bicep 文件添加到 GitHub 存储库。以下 Bicep 文件创建存储帐户：

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'

param location string = resourceGroup().location

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Bicep 文件采用一个名为 storagePrefix 的参数，其中包含 3 到 11 个字符。

你可以将该文件放到存储库中的任何位置。下一部分中的工作流示例假设 Bicep 文件名为 main.bicep，并存储在存储库的根目录中。

创建工作流

工作流定义了在触发时要执行的步骤。它是存储库的 .github/workflows/ 路径中的一个 YAML (.yml) 文件。工作流文件扩展名可以是“.yml”或“.yaml”。

若要创建工作流，请执行以下步骤：

在 GitHub 存储库的顶部菜单中，选择“操作”。
选择“新建工作流”。
选择“自己设置工作流”。
如果希望使用“main.yml”以外的其他名称，请重命名工作流文件。例如：deployBicepFile.yml。

将 yml 文件的内容替换为以下代码：

服务主体
OpenID Connect

name: Deploy Bicep file
on: [push]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:

    - name: Checkout code
      uses: actions/checkout@main

    - name: Log into Azure
      uses: azure/login@v1
      with:
        creds: ${{ secrets.AZURE_CREDENTIALS }}

    - name: Deploy Bicep file
      uses: azure/arm-deploy@v1
      with:
        subscriptionId: ${{ secrets.AZURE_SUBSCRIPTION }}
        resourceGroupName: ${{ secrets.AZURE_RG }}
        template: ./main.bicep
        parameters: 'storagePrefix=mystore storageSKU=Standard_LRS'
        failOnStdErr: false

将 mystore 替换为你自己的存储帐户名称前缀。

注意

可以改为在 ARM 部署操作中指定一个 JSON 格式的参数文件（例如：.azuredeploy.parameters.json）。

工作流文件的第一部分包含：

name：工作流的名称。
事件：触发工作流的 GitHub 事件的名称。当主分支上发生推送事件时，将触发工作流。

on: [push]
name: Azure ARM
permissions:
  id-token: write
  contents: read
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:

      # Checkout code
    - uses: actions/checkout@main

      # Log into Azure
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      # Deploy Bicep file
    - name: deploy
      uses: azure/arm-deploy@v1
      with:
        subscriptionId: ${{ secrets.AZURE_SUBSCRIPTION }}
        resourceGroupName: ${{ secrets.AZURE_RG }}
        template: ./main.bicep
        parameters: 'storagePrefix=mystore storageSKU=Standard_LRS'
        failOnStdErr: false

选择“提交更改”。
选择“直接提交到主分支”。
选择“提交新文件”（或“提交更改”）。

更新工作流文件或 Bicep 文件会触发工作流。提交更改后，工作流将立即启动。

检查工作流状态

选择“操作”选项卡。你将看到列出的“创建 deployBicepFile.yml”工作流。运行此工作流需要 1-2 分钟。
选择要打开的工作流，并验证 Status 是否为 Success。

清理资源

不再需要资源组和存储库时，请通过删除资源组和 GitHub 存储库来清理部署的资源。

CLI
PowerShell

az group delete --name exampleRG

Remove-AzResourceGroup -Name exampleRG

后续步骤

Bicep 文件结构和语法

通过