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

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

本文说明了如何在 Azure 部署环境开发人员中心或项目中添加和配置目录。

目录可用于为开发团队提供一组精选的基础结构即代码 (IaC) 模板（即环境定义）来创建环境。 可以从 GitHub 或 Azure DevOps 附加自己的源代码管理存储库作为目录，并使用环境定义指定文件夹。 部署环境将扫描文件夹以获取环境定义，使其可供开发团队创建环境。

为了进一步保护模板，将会对目录进行加密；Azure 部署环境支持使用平台托管的加密密钥进行静态加密，这些密钥由 Microsoft 为 Azure 服务托管。

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

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

在本文中，学习如何：

1. 配置项目级目录
2. 配置托管标识
3. 从 Azure Repos 或 GitHub 添加目录
4. 更新目录
5. 删除目录
6. 排查目录同步错误

配置项目级目录

在项目级别附加目录使平台工程师能够提供特定于开发团队的精选环境定义。 此外，它还使被指定为项目管理员的开发团队主管能够管理为其团队提供的环境定义。

平台工程师可以完全控制项目级的目录的使用。 必须先在开发人员中心级别启用项目级别目录的使用，然后才能将目录添加到项目中。 平台工程师还可以配置可以在项目级别使用哪些类型的目录项，例如环境定义。

默认情况下，禁用项目级别的目录的使用，并且未启用任何目录项类型。 项目级别目录中的环境定义在两种情况下同步并可用。 首先，必须在相应的开发中心级别启用基于项目的目录。 其次，必须启用项目的环境定义。

将目录添加到项目

必须先在开发中心级别启用项目级别目录，然后才能将目录添加到项目。 还应在项目级别启用环境定义。

在开发中心级别启用项目级别目录：

1. 在 Azure 门户中，导航到开发人员中心。

2. 在左侧菜单中的“设置”下选择“配置”。

   

3. 在“项目级别目录”窗格中，选择“为每个项目启用目录”，然后选择“应用”。

   

在项目中启用环境定义：

1. 在 Azure 门户中导航到你的项目。

2. 在左侧菜单中的“设置”下，选择“目录”。

   

3. 在“目录”页上，选择“目录项权限”。

   

4. 在“目录项设置”窗格中选择“Azure 部署环境定义”，以便在项目级别启用环境定义。

   

现在可以向项目添加目录了。

对于使用托管标识或个人访问令牌 (PAT) 进行身份验证的目录，必须为项目分配托管标识。 对于使用 PAT 的目录，必须将 PAT 存储在密钥保管库中，并授予托管标识对密钥保管库机密的访问权限。

配置托管标识

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

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

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

添加目录

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

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

包含 MSI 的 Azure Repos 存储库

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

• 在 Azure Repos 中为托管标识分配权限。
• 将存储库作为目录添加。

在 Azure Repos 中为托管标识分配权限

必须向托管标识授予 Azure Repos 中存储库的权限。

1. 登录到你的 Azure DevOps 组织。

   注意

   Azure DevOps 组织必须与包含开发人员中心或项目的 Azure 订阅位于同一目录中。

2. 选择 “组织设置”。

   

3. 在“概述”页上，选择“用户”。

   

4. 在“用户”页上，选择“添加用户”。

   

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

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

   

将存储库作为目录添加

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

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

1. 在 Azure 门户中，导航到开发人员中心或项目。

2. 在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。

   

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

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

   

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

包含 PAT 的 Azure Repos 存储库

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

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

获取 Azure Repos 存储库的克隆 URL

1. 转到团队集合主页（例如 https://contoso-web-team.visualstudio.com），然后选择项目。

2. 获取 Azure Repos Git 存储库的克隆 URL。

3. 复制并保存 URL。

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

1. 转到团队集合主页（例如 https://contoso-web-team.visualstudio.com），然后选择项目。

2. 创建 PAT。

3. 复制并保存生成的令牌以供以后使用。

创建密钥保管库

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

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

1. 登录 Azure 门户。

2. 在“搜索”框中输入“Key Vault”。

3. 从结果列表中选择“Key Vault”。

4. 在“Key Vault”页面上，选择“创建”。

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

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

   让其他选项保留默认值。

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

7. 在“查看 + 创建”选项卡上，选择“创建”。

如果你的组织的策略要求将 Key Vault 与 Internet 隔离，则可以将 Key Vault 设置为允许受信任的 Microsoft 服务绕过防火墙规则。

若要了解如何允许受信任的 Microsoft 服务绕过防火墙，请参阅配置 Azure Key Vault 网络设置。

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

1. 在 Key Vault 中的左侧菜单上，选择“机密”。

2. 在“机密”页面上，选择“生成/导入”。

3. 在“创建机密”页上，执行以下操作：

   • 在“名称”框中，为机密输入一个描述性名称。
   • 在“机密值”框中，粘贴之前复制的 PAT。
   • 选择创建。

获取机密标识符

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

1. 在 Azure 门户中，导航到你的密钥保管库。

2. 在密钥保管库页面上，从左侧菜单中选择“机密”。

3. 在“机密”页上，选择之前创建的机密。

4. 在版本页面上，选择“当前版本”。

5. 在当前版本页面上，针对“机密标识符”选择复制按钮。

将存储库作为目录添加

1. 在 Azure 门户中，转到开发人员中心或项目。

2. 确保附加到开发人员中心或项目的标识有权访问密钥保管库机密（其中存储了个人访问令牌）。

3. 在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。

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

   字段	值
   名称	输入目录的名称。
   目录位置	选择“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

   

5. 在“目录”中，验证目录是否显示。 如果连接成功，则“状态”为“已连接”。

包含 DevCenter 应用的 GitHub 存储库

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

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

安装 Microsoft 开发人员中心应用

1. 登录 Azure 门户。

2. 导航到你的开发人员中心或项目。

3. 在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。

4. 在“添加目录”窗格中，输入或选择以下内容：

   字段	值
   名称	输入目录的名称。
   目录源	选择“GitHub”。
   身份验证类型	选择“GitHub 应用”。

5. 若要安装 Microsoft 开发人员中心应用，请选择“配置存储库”。

   

6. 如果系统提示你向 GitHub 进行身份验证，请进行身份验证。

7. 在“Microsoft DevCenter”页上，选择“配置”。

   

8. 选择包含要添加为目录的存储库的 GitHub 组织。 你必须是组织的所有者才能安装此应用。

   

9. 在“安装 Microsoft DevCenter”页面上，依次选择“仅选择存储库”、要添加为目录的存储库、“安装”。

   

   可以选择多个要添加为目录的存储库。 必须将每个存储库添加为单独的目录，如将存储库添加为目录中所述。

10. 在“Microsoft 的 Microsoft DevCenter 想要获得以下权限:”页面上，查看所需的权限，然后选择“授权 Microsoft 开发人员中心”。

    

将存储库作为目录添加

1. 切换回 Azure 门户。

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

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

   

3. 在“目录”中，验证目录是否显示。 连接成功后，“状态”会显示为“同步成功”。

   

包含 PAT 的 GitHub 存储库

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

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

获取 GitHub 存储库的克隆 URL

1. 转到包含模板定义的 GitHub 存储库的主页。

2. 获取 GitHub 存储库克隆 URL。

3. 复制并保存 URL。

在 GitHub 中创建个人访问令牌

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

1. 转到包含模板定义的 GitHub 存储库的主页。

2. 选择 GitHub 右上角的配置文件图像，然后选择“设置”。

3. 在左侧边栏中，选择“开发人员设置”>“个人访问令牌”>“细粒度令牌”。

4. 选择“生成新令牌”。

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

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

   

6. 选择“生成令牌”。

7. 复制并保存生成的令牌以供以后使用。

重要

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

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

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

创建密钥保管库

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

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

1. 登录 Azure 门户。

2. 在搜索框中输入“Key Vault”。

3. 从结果列表中选择“Key Vault”。

4. 在“Key Vault”页面上，选择“创建”。

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

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

   让其他选项保留默认值。

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

7. 在“查看 + 创建”选项卡上，选择“创建”。

如果你的组织的策略要求将 Key Vault 与 Internet 隔离，则可以将 Key Vault 设置为允许受信任的 Microsoft 服务绕过防火墙规则。

若要了解如何允许受信任的 Microsoft 服务绕过防火墙，请参阅配置 Azure Key Vault 网络设置。

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

1. 在 Key Vault 中的左侧菜单上，选择“机密”。

2. 在“机密”页面上，选择“生成/导入”。

3. 在“创建机密”页上，执行以下操作：

   • 在“名称”框中，为机密输入一个描述性名称。
   • 在“机密值”框中，粘贴 PAT。
   • 选择创建。

获取机密标识符

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

1. 在 Azure 门户中，导航到你的密钥保管库。

2. 在密钥保管库页面上，从左侧菜单中选择“机密”。

3. 在“机密”页上，选择之前创建的机密。

4. 在版本页面上，选择“当前版本”。

5. 在当前版本页面上，针对“机密标识符”选择复制按钮。

将存储库作为目录添加

1. 在 Azure 门户中，转到开发人员中心或项目。

2. 确保附加到开发人员中心或项目的托管标识有权访问密钥保管库机密（其中存储了个人访问令牌）。

3. 在左侧菜单中的“环境配置”下选择“目录”，然后选择“添加”。

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

   字段	值
   名称	输入目录的名称。
   目录位置	选择“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

   

5. 在“目录”中，验证目录是否显示。 连接成功后，“状态”会显示为“同步成功”。

查看同步的目录项

无论使用的存储库类型如何，都可以查看从目录中同步的目录项。

1. 在开发人员中心或项目的左侧菜单中的“环境配置”下，选择“目录”。

2. 在“目录”窗格中，选择目录名称。

   

3. 你将看到已成功同步的目录项的列表。

   

更新目录

如果更新附加存储库中的定义或模板内容，则可通过同步目录向开发团队提供最新的环境定义集。 可以手动或自动同步目录。

手动同步目录

手动同步目录时，部署环境将扫描存储库，并向开发人员中心内所有关联项目提供最新的环境定义列表。

1. 在开发人员中心的左侧菜单中的“环境配置”下，选择“目录”。

2. 选择特定目录，然后在命令栏中选择“同步”。

   

自动同步目录

将目录配置为自动同步时，部署环境将每 30 分钟扫描一次存储库，并向开发人员中心内所有关联项目提供最新的环境定义列表。

1. 在开发人员中心或项目的左侧菜单中的“环境配置”下，选择“目录”。

2. 选择特定目录，然后选择“编辑”。

   

3. 在“编辑目录”窗格中，选择“自动同步此目录”，然后选择“保存”。

   

删除目录

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

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

1. 在开发人员中心或项目的左侧菜单中的“环境配置”下，选择“目录”。

2. 选择特定目录，然后选择“删除”。

3. 在“删除目录”对话框中，选择“继续”以删除目录。

排查目录同步错误

添加或同步目录时，可能会遇到同步错误或警告。 同步错误指示目录无法成功同步，同步警告指示部分或所有目录项都存在错误。 可以在 Azure 门户中查看同步状态和错误，或使用 Azure CLI 和 REST API 排查和解决错误。

查看目录同步状态

在 Azure 门户中，可以通过选择状态链接获取有关目录同步状态以及任何警告或错误的详细信息。 点击状态链接将打开一个窗格，其中显示了同步状态、已添加的环境定义数量以及已忽略或失败的环境定义数量。

查看目录同步失败

1. 在开发人员中心或项目的左侧菜单中的“环境配置”下，选择“目录”。

2. 在“状态”列中，选择同步失败的目录的状态链接。

   

3. 你将看到一个结果窗格，其中显示了上次同步的变化、同步错误数量和错误类型。

   

查看目录同步警告

1. 在开发人员中心或项目的左侧菜单中的“环境配置”下，选择“目录”。

2. 在“状态”列中，选择已同步但报告警告的目录的状态链接。

   

3. 你将看到一个细节窗格，其中显示了上次同步的变化、项错误数量以及每个错误的类型和源。

   

4. 可以查看从也报告同步错误的目录成功同步的项。 在“目录”窗格中，选择目录名称。

   

5. 你将看到已成功同步的目录项的列表。

   

使用 Azure CLI 排查目录同步错误

使用 Azure CLI 或 REST API 来 GET 目录。 GET 响应会显示错误类型：

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

解决忽略的环境定义错误

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

解决无效的环境定义错误

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

• 清单架构错误。 确保环境定义环境文件与所需的架构匹配。

• 验证错误。 请检查以下各项以解决验证错误：

  • 确保正确配置环境文件的引擎类型。
  • 确保环境定义名称介于 3 到 63 个字符之间。
  • 确保环境定义名称仅包含对 URL 有效的字符，即字母数字字符和以下符号：~!,.';:=-_+()*&$@

• 引用错误。 确保环境文件引用的模板路径是指向存储库中文件的有效相对路径。

相关内容

• 为开发人员中心配置环境类型
• 使用 Azure CLI 创建和配置项目
• 配置项目环境类型