你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 GitHub 或 Azure Repos 中添加和配置目录

项目
04/26/2024

本指南说明了如何在 Azure 部署环境开发人员中心中添加和配置目录。目录是托管在 GitHub 或 Azure DevOps 中的存储库。

可以使用目录为开发团队提供一组名为环境定义的精选基础架构即代码 (IaC) 模板。

部署环境支持 Azure Repos（Azure 中的存储库服务，通常称为 Azure DevOps）中托管的目录和 GitHub 中托管的目录。 Azure Repos 支持通过向托管标识分配权限进行身份验证。 Azure Repos 和 GitHub 都支持使用个人访问令牌 (PAT) 进行身份验证。为了进一步保护模板，将会对目录进行加密；Azure 部署环境支持使用平台托管的加密密钥进行静态加密，这些密钥由 Microsoft 为 Azure 服务托管。

若要了解如何在 GitHub 中托管存储库，请参阅 GitHub 入门。
若要了解如何在 Azure Repos 项目中托管 Git 存储库，请参阅 Azure Repos。

Microsoft 提供了一个可以添加到开发人员中心的快速启动目录，以及一个可以用作存储库的示例目录。你也可以使用自己的专用存储库，或者对示例目录中的环境定义创建分支并进行自定义。

为开发人员中心配置托管标识

创建开发人员中心后，必须先为开发人员中心配置托管标识（也称为托管服务标识 (MSI)），然后才能附加目录。可以附加系统分配的托管标识（系统分配的 MSI）或用户分配的托管标识（用户分配的 MSI）。然后，将角色分配给托管标识，以允许开发人员中心在订阅中创建环境类型，并读取包含目录存储库的 Azure Repos 项目。

如果开发人员中心未附加 MSI，请按照配置托管标识中的步骤创建一个，然后分配开发人员中心托管标识的角色。

要详细了解托管标识，请参阅什么是 Azure 资源的托管标识？

添加目录

可以从 Azure Repos 存储库或 GitHub 存储库添加目录。可以选择通过向 MSI 分配权限或使用存储在密钥保管库中的 PAT 进行身份验证。

为要使用的存储库和身份验证类型选择选项卡。

要添加目录，请完成以下任务：

在 Azure Repos 中为开发人员中心托管标识分配权限。
将存储库作为目录添加。

在 Azure Repos 中为开发人员中心托管标识分配权限

必须向开发人员中心托管标识授予 Azure Repos 中存储库的权限。

登录到你的 Azure DevOps 组织。

注意

Azure DevOps 组织必须与包含开发人员中心的 Azure 订阅位于同一目录中。
选择 “组织设置”。
在“概述”页上，选择“用户”。
在“用户”页上，选择“添加用户”。

输入或选择以下信息完成“添加新用户”，然后选择“添加”：

名称	值
用户或服务主体	输入开发人员中心的名称。使用系统分配的 MSI 时，请指定开发人员中心的名称，而不是托管帐户的对象 ID。使用用户分配的 MSI 时，请使用托管帐户的名称。
访问级别	选择“基本”。
添加到项目	选择包含存储库的项目。
Azure DevOps 组	选择“项目读取者”。
发送电子邮件邀请（仅限用户）	清除该复选框。

将存储库作为目录添加

Azure 部署环境支持附加 Azure Repos 存储库和 GitHub 存储库。你可以将一组特选的 IaC 模板存储在存储库中。将存储库作为目录附加到开发人员中心，使开发团队能够访问模板，并使其能够快速创建一致的环境。

借助以下步骤，可以附加 Azure Repos 存储库。

在 Azure 门户中，导航到开发人员中心。
在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。

在“添加目录”中，输入以下信息，然后选择“添加”：

字段	值
名称	输入目录的名称。
目录位置	选择“Azure DevOps”。
身份验证类型	选择“托管标识”。
组织	选择 Azure DevOps 组织。
Project	从项目列表中，选择存储存储库的项目。
存储库	从存储库列表中，选择要添加的存储库。
分支	选择分支。
文件夹路径	Dev Box 检索分支中的文件夹列表。选择存储 IaC 模板的文件夹。

在开发人员中心的“目录”中，验证目录是否显示。连接成功后，“状态”会显示为“同步成功”。首次连接到目录可能需要几分钟时间。

要添加目录，请完成以下任务：

获取 Azure Repos 存储库的克隆 URL。
创建个人访问令牌 (PAT)。
将 PAT 存储为 Azure 密钥保管库中的密钥保管库机密。
将存储库作为目录添加。

获取 Azure Repos 存储库的克隆 URL

转到团队集合主页（例如 https://contoso-web-team.visualstudio.com），然后选择项目。
获取 Azure Repos Git 存储库的克隆 URL。
复制并保存 URL。

在 Azure Repos 中创建个人访问令牌

转到团队集合主页（例如 https://contoso-web-team.visualstudio.com），然后选择项目。
创建 PAT。
复制并保存生成的令牌以供以后使用。

创建密钥保管库

需要一个 Azure 密钥保管库来存储用于向 Azure 授予对存储库访问权限的 PAT。密钥保管库可以使用访问策略或基于角色的访问控制 (RBAC) 来控制访问。如果已有密钥保管库，可以使用，但要检查它是否使用访问策略或 RBAC 分配来控制访问。有关为密钥保管库配置访问策略的帮助，请参阅分配密钥保管库访问策略。

使用以下步骤创建 RBAC 密钥保管库：

登录 Azure 门户。
在“搜索”框中输入“Key Vault”。
从结果列表中选择“Key Vault”。
在“Key Vault”页面上，选择“创建”。

在“创建密钥保管库”选项卡上，提供以下信息：

名称	值
名称	输入密钥保管库的名称。
订阅	选择要在其中创建密钥保管库的订阅。
资源组	使用现有资源组，或者选择“新建”并输入资源组的名称。
位置	选择要在其中创建密钥保管库的位置或区域。

让其他选项保留默认值。

在“访问策略”选项卡上，选择“Azure 基于角色的访问控制”，然后选择“查看 + 创建”。
在“查看 + 创建”选项卡上，选择“创建”。

将个人访问令牌存储在密钥保管库中

在 Key Vault 中的左侧菜单上，选择“机密”。
在“机密”页面上，选择“生成/导入”。
在“创建机密”页上，执行以下操作：
- 在“名称”框中，为机密输入一个描述性名称。
- 在“机密值”框中，粘贴之前复制的 PAT。
- 选择创建。

获取机密标识符

获取在密钥保管库中创建的机密的路径。

在 Azure 门户中，导航到你的密钥保管库。
在密钥保管库页面上，从左侧菜单中选择“机密”。
在“机密”页上，选择之前创建的机密。
在版本页面上，选择“当前版本”。
在当前版本页面上，针对“机密标识符”选择复制按钮。

将存储库作为目录添加

在 Azure 门户中转到你的开发人员中心。
确保附加到开发人员中心的标识有权访问密钥保管库机密（其中存储了个人访问令牌）。
在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。

在“添加目录”中，输入以下信息，然后选择“添加”：

字段	值
名称	输入目录的名称。
目录位置	选择“Azure DevOps”。
身份验证类型	选择“个人访问令牌”。
组织	选择托管目录存储库的组织。
项目	选择存储目录存储库的项目。
Rep	选择存储目录的存储库。
文件夹路径	选择保存 IaC 模板的文件夹。
机密标识符	输入包含存储库 PAT 的机密标识符。复制机密标识符时，连接字符串末尾包含一个版本标识符，如下所示：`https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a`。删除版本标识符可确保部署环境从密钥保管库中提取最新版本的机密。如果 PAT 过期，只需更新密钥保管库即可。示例机密标识符：`https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat`

在开发人员中心的“目录”中，验证目录是否显示。如果连接成功，则“状态”为“已连接”。

要添加目录，请完成以下任务：

安装和配置 Microsoft 开发人员中心应用
在 GitHub 中为存储库分配权限。
将存储库作为目录添加。

安装 Microsoft 开发人员中心应用

登录 Azure 门户。
导航到你的开发人员中心。
在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。
在“添加目录”窗格中，输入或选择以下内容：

字段值

名称输入目录的名称。

目录源选择“GitHub”。

身份验证类型 选择“GitHub 应用”。
若要安装 Microsoft 开发人员中心应用，请选择“配置存储库”。
如果系统提示你向 GitHub 进行身份验证，请进行身份验证。
在“Microsoft DevCenter”页上，选择“配置”。
选择包含要添加为目录的存储库的 GitHub 组织。你必须是组织的所有者才能安装此应用。
在“安装 Microsoft DevCenter”页面上，依次选择“仅选择存储库”、要添加为目录的存储库、“安装”。

可以选择多个要添加为目录的存储库。必须将每个存储库添加为单独的目录，如将存储库添加为目录中所述。
在“Microsoft 的 Microsoft DevCenter 想要获得以下权限:”页面上，查看所需的权限，然后选择“授权 Microsoft 开发人员中心”。

将存储库作为目录添加

切换回 Azure 门户。
在“添加目录”中，输入以下信息，然后选择“添加”：

字段值

存储库 选择要添加为目录的存储库。

分支选择分支。

文件夹路径 选择所含子文件夹用于保存环境定义的文件夹。
在开发人员中心的“目录”中，验证目录是否显示。连接成功后，“状态”会显示为“同步成功”。

字段	值
存储库	选择要添加为目录的存储库。
分支	选择分支。
文件夹路径	选择所含子文件夹用于保存环境定义的文件夹。

要添加目录，请完成以下任务：

获取 GitHub 存储库的克隆 URL。
在 GitHub 中创建个人访问令牌 (PAT)。
将 PAT 存储为 Azure 密钥保管库中的密钥保管库机密。
将存储库作为目录添加。

获取 GitHub 存储库的克隆 URL

转到包含模板定义的 GitHub 存储库的主页。
获取 GitHub 存储库克隆 URL。
复制并保存 URL。

在 GitHub 中创建个人访问令牌

Azure 部署环境支持通过使用经典令牌或细粒度令牌向 GitHub 存储库进行身份验证。在此示例中，你将创建细粒度令牌。

转到包含模板定义的 GitHub 存储库的主页。
选择 GitHub 右上角的配置文件图像，然后选择“设置”。
在左侧边栏中，选择“开发人员设置”>“个人访问令牌”>“细粒度令牌”。
选择“生成新令牌”。

在“新建精细个人访问令牌”页上，提供以下信息：

名称	值
令牌名称	输入令牌的描述性名称。
过期日期	选择令牌过期期限（以天为单位）。
说明	输入令牌的说明。
资源所有者	选择存储库的所有者。
存储库访问	选择“仅选择存储库”。
选择存储库	选择包含环境定义的存储库。
存储库权限	展开“存储库权限”，对于“内容”，请从“访问权限”列表选择“代码读取”。

选择“生成令牌”。
复制并保存生成的令牌以供以后使用。

重要

使用存储在 GitHub 组织中的专用存储库时，必须确保将 GitHub PAT 配置为授予对正确组织和其中存储库的访问权限。

在创建特定组织后，组织内的经典令牌必须经过 SSO 授权。
细粒度令牌必须将令牌所有者设置为要获得授权的组织本身。

如果 PAT 配置错误，可能会导致“找不到存储库”错误。

创建密钥保管库

需要使用 Azure 密钥保管库来存储用于授予 Azure 对存储库访问权限的 PAT。密钥保管库可以使用访问策略或基于角色的访问控制 (RBAC) 来控制访问。如果已有密钥保管库，可以使用，但要检查它是否使用访问策略或 RBAC 分配来控制访问。有关为密钥保管库配置访问策略的帮助，请参阅分配密钥保管库访问策略。

使用以下步骤创建 RBAC 密钥保管库：

登录 Azure 门户。
在搜索框中输入“Key Vault”。
从结果列表中选择“Key Vault”。
在“Key Vault”页面上，选择“创建”。

在“创建密钥保管库”选项卡上，提供以下信息：

名称	值
名称	输入密钥保管库的名称。
订阅	选择要在其中创建密钥保管库的订阅。
资源组	使用现有资源组，或者选择“新建”并输入资源组的名称。
位置	选择要在其中创建密钥保管库的位置或区域。

让其他选项保留默认值。

在“访问策略”选项卡上，选择“Azure 基于角色的访问控制”，然后选择“查看 + 创建”。
在“查看 + 创建”选项卡上，选择“创建”。

将个人访问令牌存储在密钥保管库中

在 Key Vault 中的左侧菜单上，选择“机密”。
在“机密”页面上，选择“生成/导入”。
在“创建机密”页上，执行以下操作：
- 在“名称”框中，为机密输入一个描述性名称。
- 在“机密值”框中，粘贴 PAT。
- 选择创建。

获取机密标识符

获取在密钥保管库中创建的机密的路径。

在 Azure 门户中，导航到你的密钥保管库。
在密钥保管库页面上，从左侧菜单中选择“机密”。
在“机密”页上，选择之前创建的机密。
在版本页面上，选择“当前版本”。
在当前版本页面上，针对“机密标识符”选择复制按钮。

将存储库作为目录添加

在 Azure 门户中转到你的开发人员中心。
确保附加到开发人员中心的托管标识有权访问密钥保管库机密（其中存储了个人访问令牌）。
在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。

在“添加目录”中，输入以下信息，然后选择“添加”。

字段	值
名称	输入目录的名称。
目录位置	选择“GitHub”。
存储库	输入或粘贴 GitHub 存储库或 Azure Repos 存储库的克隆 URL。目录示例：`https://github.com/Azure/deployment-environments.git`
分支	输入要连接到的存储库分支。目录示例：`main`
文件夹路径	输入与克隆 URI 相对的文件夹路径，其中包含保存环境定义的子文件夹。文件夹路径适用于子文件夹中包含环境定义环境文件的文件夹，而不适用于包含环境定义环境文件的文件夹本身。下图显示了示例目录文件夹的结构。目录示例：`/Environments` 文件夹路径可以以正斜杠开头，也可以不带正斜杠 (`/`)。
机密标识符	输入包含存储库 PAT 的机密标识符。复制机密标识符时，连接字符串末尾包含一个版本标识符，如下所示：`https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a`。移除版本标识符可确保部署环境从密钥保管库中提取最新版本的机密。如果 PAT 过期，只需更新密钥保管库即可。示例机密标识符：`https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat`

在开发人员中心的“目录”中，验证目录是否显示。连接成功后，“状态”会显示为“同步成功”。

更新目录

如果更新附加存储库中的 Azure 资源管理器模板（ARM 模板）内容或定义，则可通过同步目录向开发团队提供最新的环境定义集。

要在 Azure 部署环境中同步更新后的目录，请执行以下操作：

在开发人员中心的左侧菜单中的“环境配置”下，选择“目录”。
选择特定目录，然后选择“同步”。该服务会扫描存储库，并向开发人员中心内所有关联项目提供最新的环境定义列表。

删除目录

可以删除目录，以将其从 Azure 部署环境开发人员中心中移除。在开发团队部署新环境时，将无法使用已删除目录中的模板。更新使用已删除目录中的环境定义创建的任何现有环境的环境定义引用。如果未更新引用并重新部署环境，则会导致部署失败。

若要删除目录，请执行以下操作：

在开发人员中心的左侧菜单中的“环境配置”下，选择“目录”。
选择特定目录，然后选择“删除”。
在“删除目录”对话框中，选择“继续”以删除目录。

目录同步错误

添加或同步目录时，可能会遇到同步错误。同步错误指示一些或所有环境定义存在错误。使用 Azure CLI 或 REST API 来 GET 目录。 GET 响应会显示错误类型：

忽略了检测为重复项的环境定义。
由于架构、引用或验证错误而失败的环境定义无效。

解决忽略的环境定义错误

如果添加两个或更多具有相同名称的环境定义，则会发生被忽略的环境定义错误。可以通过重命名环境定义来解决此问题，以便每个环境定义在目录中具有唯一的名称。

解决无效的环境定义错误

环境定义无效错误可能出于各种原因：

清单架构错误。确保环境定义环境文件与所需的架构匹配。
验证错误。请检查以下各项以解决验证错误：
- 确保将环境文件的引擎类型正确配置为 ARM。
- 确保环境定义名称介于 3 到 63 个字符之间。
- 确保环境定义名称仅包含对 URL 有效的字符，即字母数字字符和以下符号：~!,.';:=-_+()*&$@
引用错误。确保环境文件引用的模板路径是指向存储库中文件的有效相对路径。

在 GitHub 或 Azure Repos 中添加和配置目录

为开发人员中心配置托管标识