适用于 Git 存储库的管道选项

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

编辑使用 Git 存储库的管道期间（在 Azure DevOps 项目、GitHub、GitHub Enterprise Server、Bitbucket Cloud 或其他 Git 存储库中），可以使用以下选项。

分支

这是你希望在手动将此生成排队时作为默认分支的分支。 如果为生成设置计划触发器，则生成将从中获取最新源的分支。 通过持续集成 (CI) 触发生成时，默认分支没有任何影响。 通常会将此设置为与存储库默认分支相同（例如“主分支”）。

清理代理上的本地存储库

在生成运行之前，可以对自托管代理的工作目录执行不同形式的清理。

一般情况下，为了提高自托管代理的性能，请不要清理存储库。 在这种情况下，若要获得最佳性能，请确保同时以增量方式生成，方法是禁用用于生成的任务或工具的任何“清理”选项。

如果你确实需要清理存储库（例如，为了避免上次生成残留的文件造成问题），请使用以下选项。

parameters:
- name: clean
  displayName: Checkout clean
  type: boolean
  default: true
  values:
  - false
  - true

trigger:
- main

pool: FabrikamPool
#  vmImage: 'ubuntu-latest'

steps:
- checkout: self
  clean: ${{ parameters.clean }}

标记源

你可能想要标记源代码文件，使团队能够轻松确定每个文件的哪个版本包含在已完成的生成中。 还可以选择指定是应为所有生成标记源代码，还是仅为成功的生成标记源代码。

在“标签格式”中，可以使用范围为“全部”的用户定义变量和预定义变量。例如：

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)

前四个变量是预定义变量。 My.Variable 可以是你在“变量”选项卡上定义的变量。

生成管道使用 Git 标记标记源。

某些生成变量可能会生成不是有效标签的值。 例如，$(Build.RequestedFor) 和 $(Build.DefinitionName) 等变量可以包含空格。 如果值包含空格，则不会创建标记。

生成管道标记源后，带有 Git 引用 refs/tags/{tag} 的项目会自动添加到已完成的生成中。 这为团队提供了额外的可跟踪性，并提供更加用户友好的方式来从生成导航到生成的代码。 标记被视为生成项目，因为它是由生成创建的。 手动或通过保留策略删除生成时，也会删除标记。

报表生成状态（Azure Pipelines、TFS 2018 及更高版本）

可以选择向团队提供远程源存储库中生成状态的视图。

如果源位于项目中的 Azure Repos Git 存储库中，则此选项会在“代码”页上显示一个锁屏提醒，以指示生成是通过还是失败。 生成状态显示在以下选项卡中：

• 文件：指示所选分支的最新生成状态。
• 提交：指示每个提交的生成状态（这需要为生成启用持续集成 (CI) 触发器）。
• 分支：指示每个分支的最新生成状态。

如果在项目中对同一存储库使用多个生成管道，则可以选择为一个或多个管道启用此选项。 在多个管道上启用此选项的情况下，“代码”页上的锁屏提醒指示所有管道中最新生成的状态。 团队成员可以单击生成状态锁屏提醒，以查看每个生成管道的最新生成状态。

其他类型的 Git 远程存储库

如果源位于任何其他类型的远程存储库中，则无法使用 Azure Pipelines 或 TFS 自动将生成状态发布到该存储库。 但是，可以使用生成锁屏提醒在版本控制体验中集成和显示生成状态。

签出子模块

选择是否要从子模块下载文件。 可以选择获取即时子模块或嵌套到任何递归深度的所有子模块。 如果要将 LFS 与子模块一起使用，请务必查看有关将 LFS 与子模块配合使用的说明。

生成管道将签出 Git 子模块，只要它们是：

• 未经身份验证：一个未经身份验证的公共存储库，无需凭据即可克隆或提取。

• 已经过身份验证：

  • 包含在上面指定的 Git 存储库所在的同一项目、GitHub 组织或 Bitbucket 云帐户中。

  • 通过使用相对于主存储库的 URL 添加。 例如，将签出子模块：git submodule add /../../submodule.git mymodule；不会签出子模块：git submodule add https://dev.azure.com/fabrikamfiber/_git/ConsoleApp mymodule

经过身份验证的子模块

代理用于从主存储库获取源的凭据也用于获取子模块的源。

如果主存储库和子模块位于 Azure DevOps 项目的 Azure Repos Git 存储库中，则可以选择用于访问源的帐户。 在“选项”选项卡上的“生成作业授权范围”菜单上，选择以下任一项：

• 使用项目集合生成服务帐户的项目集合

• 使用项目生成服务帐户的当前项目。

请确保使用的每个帐户都有权访问主存储库和子模块。

如果主存储库和子模块位于同一 GitHub 组织中，则存储在 GitHub 服务连接中的令牌用于访问源。

使用“签出子模块”选项的替代方法

在某些情况下，无法使用“签出子模块”选项。 你可能会遇到这样一种情况：需要一组不同的凭据才能访问子模块。 例如，如果主存储库和子模块存储库不存储在同一个 Azure DevOps 组织或 Git 服务中，则可能会发生这种情况。

如果无法使用“签出子模块”选项，则可以改用自定义脚本步骤来提取子模块。 首先，获取个人访问令牌 (PAT)，并添加前缀 pat:。 接下来，对添加前缀后的字符串进行 base64 编码，以创建基本身份验证令牌。 最后，将此脚本添加到管道：

git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: basic <BASE64_ENCODED_TOKEN_DESCRIBED_ABOVE>" submodule update --init --recursive

请务必将“<BASIC_AUTH_TOKEN>”替换为 Base64 编码的令牌。

在项目或生成管道中使用机密变量来存储生成的基本身份验证令牌。 使用该变量在上述 Git 命令中填充机密。

从 LFS 签出文件

选择是否要从大型文件存储 (LFS) 下载文件。

在经典编辑器中，选择复选框来启用此选项。

在 YAML 生成中，添加一个签出步骤，将 lfs 设置为 true：

steps:
- checkout: self
  lfs: true

如果使用 TFS，或者将 Azure Pipelines 与自托管代理一起使用，则必须在代理上安装 git-lfs 才能使此选项生效。 如果托管代理使用 Windows，请考虑使用 System.PreferGitFromPath 变量，以确保管道使用计算机上安装的 git 和 git-lfs 版本。 有关详细信息，请参阅我的代理运行哪个版本的 Git？

将 Git LFS 与子模块配合使用

如果子模块包含 LFS 文件，则必须在签出子模块之前配置 Git LFS。 Microsoft 托管的 macOS 和 Linux 代理以这种方式进行预配置。 Windows 代理和自托管 macOS/Linux 代理可能不会。

steps:
- script: |
    git config --global --add filter.lfs.required true
    git config --global --add filter.lfs.smudge "git-lfs smudge -- %%f"
    git config --global --add filter.lfs.process "git-lfs filter-process"
    git config --global --add filter.lfs.clean "git-lfs clean -- %%f"
  displayName: Configure LFS for use with submodules
- checkout: self
  lfs: true
  submodules: true
# ... rest of steps ...

克隆第二个存储库

默认情况下，管道与来自 Azure Repos 或外部提供程序的一个存储库关联。 这是可以在提交和拉取请求时触发生成的存储库。

你可能希望在管道中包含来自第二个存储库的源。 可以通过编写脚本来执行此操作。

git clone https://github.com/Microsoft/TypeScript.git

如果存储库不是公共存储库，则需要将身份验证传递给 Git 命令。

Azure Repos

如果需要从另一个非公共项目克隆存储库，则需要以有权访问该项目的用户身份进行身份验证。

对于 Azure Repos，可以使用具有“代码(读取)”权限的个人访问令牌。 将此作为密码字段发送到“基本”授权标头中，不带用户名。 （换句话说，对 :<PAT> 的值进行 base64 编码，包括冒号。）

AUTH=$(echo -n ":$REPO_PAT" | openssl base64 | tr -d '\n')
git -c http.<repo URL>.extraheader="AUTHORIZATION: basic $AUTH" clone <repo URL> --no-checkout --branch master

不同步源

非部署作业会自动提取源。 如果要跳过该行为，请使用此选项。 此选项在需要执行以下操作的情况下非常有用：

• 使用自己的自定义选项进行 Git 初始化、配置和提取。

• 使用生成管道仅运行不依赖于版本控制中的代码的自动化（例如，某些脚本）。

如果要禁用下载源：

• Azure Pipelines、TFS 2018 及更高版本：单击“高级设置”，然后选择“不同步源”。

浅提取

如果要限制下载历史记录的时间，请选择此选项。 这实际上会导致 git fetch --depth=n。 如果存储库很大，此选项可能会提高生成管道的效率。 如果存储库已长期使用并且具有相当大的历史记录，则存储库可能很大。 如果添加并随后删除了大型文件，则它也可能很大。

在这些情况下，此选项有助于节省网络和存储资源。 它还可以节省时间。 但它并不是一定会节省时间，原因是，在某些情况下，服务器可能需要花时间计算要为指定深度下载的提交。

选中复选框启用此选项后，在“深度”框中指定提交数。

首选路径中的 Git

默认情况下，Windows 代理使用与代理软件捆绑在一起的 Git 版本。 Microsoft 建议使用与代理捆绑在一起的 Git 版本，但有多个选项可以替代此默认行为，并使用代理计算机在路径中安装的 Git 版本。

• 在管道中将名为 System.PreferGitFromPath 的管道变量设置为 true。
• 在自托管代理上，可以在代理根目录中创建名为 .env 的文件，并在文件中添加 System.PreferGitFromPath=true 行。 有关详细信息，请参阅如何为每个单独的代理设置不同的环境变量？

若要查看管道使用的 Git 版本，可以查看管道中 checkout 步骤的日志，如以下示例所示。

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

在非 Windows 代理上，此设置始终为 true。

其他 Git 的触发器选项

指定其他/外部 Git 存储库时，CI 生成要求可以从 Internet 访问该存储库。 如果存储库位于防火墙或代理后面，则只有计划和手动生成才能正常工作。

FAQ

生成代理可以将哪些协议与 Git 配合使用？

代理支持 HTTPS。

代理尚不支持 SSH。 请参阅在签出 Git 子模块时允许生成使用 SSH 身份验证。