通过

生成 GitHub Enterprise 服务器存储库

  • 项目

Azure DevOps Services

可以将本地 GitHub Enterprise Server 与 Azure Pipelines 集成。 你的本地服务器可能会在 Internet 中公开，也可能不会公开。

如果可以从运行 Azure Pipelines 服务的服务器访问你的 GitHub Enterprise Server，那么：

  • 可以设置经典生成管道和 YAML 管道
  • 可以配置 CI、PR 和计划触发器

如果无法从运行 Azure Pipelines 服务的服务器访问你的 GitHub Enterprise Server，那么：

  • 只能设置经典生成管道
  • 只能启动手动或计划的生成
  • 无法设置 YAML 管道
  • 无法为经典生成管道配置 CI 或 PR 触发器

如果可从 Microsoft 托管代理访问你的本地服务器，则可以使用这些代理来运行管道。 否则，必须设置可以访问本地服务器并提取代码的自托管代理。

可从 Azure Pipelines 访问

要检查的第一件事是是否可以从 Azure Pipelines 服务访问 GitHub Enterprise Server。

  1. 在 Azure DevOps UI 中，导航到项目设置，然后在“管道”下选择“服务连接”。
  2. 选择“新建服务连接”，然后选择“GitHub Enterprise Server”作为连接类型。
  3. 输入所需的信息以创建与 GitHub Enterprise Server 的连接。
  4. 在服务连接面板中选择“验证”。

如果验证通过，则运行 Azure Pipelines 服务的服务器能够访问本地 GitHub Enterprise Server。 可以继续并设置连接了。 然后，可以在创建经典生成管道或 YAML 管道时使用此服务连接。 还可以为管道配置 CI 和 PR 触发器。 Azure Pipelines 中适用于 GitHub 的大多数功能也适用于 GitHub Enterprise Server。 查看 GitHub 的文档可了解这些功能。 下面是一些差异：

  • GitHub 市场中的 Azure Pipelines 应用简化了 GitHub 与 Azure Pipelines 之间的集成。 使用此应用可以设置集成，而无需依赖特定用户的 OAuth 令牌。 我们没有适用于 GitHub Enterprise Server 的类似应用。 因此，必须使用 PAT、用户名和密码或 OAuth 来设置 Azure Pipelines 与 GitHub Enterprise 服务器之间的连接。
  • Azure Pipelines 支持许多 GitHub 安全功能来验证外部分支的贡献。 例如，管道中存储的机密不可用于正在运行的作业。 使用 GitHub Enterprise 服务器时，这些保护不可用。
  • 注释触发器不可用于 GitHub Enterprise 服务器。 不能在 GitHub Enterprise 服务器存储库拉取请求中使用注释来触发管道。
  • 注释检查在 GitHub Enterprise 服务器中不可用。 所有状态更新都通过基本状态进行。

无法从 Azure Pipelines 访问

当上一部分所述的 GitHub Enterprise Server 连接验证失败时，Azure Pipelines 无法与你的服务器通信。 这很可能是由于你的企业网络设置方式导致的。 例如，网络中的防火墙可能会阻止外部流量到达你的服务器。 在这种情况下，可以采取两种做法：

  • 与 IT 部门协作，在 Azure Pipelines 和 GitHub Enterprise Server 之间打开网络路径。 例如，可以在防火墙规则中添加例外，以允许来自 Azure Pipelines 的流量通过。 请参阅 Azure DevOps IP 部分，了解需要允许哪些 IP 地址。 此外，还需要为 GitHub Enterprise Server 创建一个公共 DNS 条目，使 Azure Pipelines 能够将你的服务器的 FQDN 解析为 IP 地址。 完成所有这些更改后，尝试在 Azure Pipelines 中创建并验证 GitHub Enterprise Server 连接。

  • 可以使用其他 Git 连接，而不是使用 GitHub Enterprise Server 连接。 请确保取消选中“尝试从 Azure Pipelines 访问此 Git 服务器”选项。 使用此连接类型时，只能配置经典生成管道。 CI 和 PR 触发器在此配置中不起作用。 只能启动手动或计划的管道运行。

可从 Microsoft 托管的代理访问

可能需要做出的另一项决定是要使用 Microsoft 托管的代理还是自托管代理来运行管道。 这通常取决于 Microsoft 托管代理能否访问你的服务器。 若要检查是否可访问，请创建一个简单管道以使用 Microsoft 托管的代理，并确保添加一个步骤以从你的服务器签出源代码。 如果通过了此检查，则你可以继续使用 Microsoft 托管的代理。

无法从 Microsoft 托管代理访问

如果上一部分所述的简单测试管道失败并出现错误 TF401019: The Git repository with name or identifier <your repo name> does not exist or you do not have permissions for the operation you are attempting，则无法从 Microsoft 托管代理访问 GitHub Enterprise Server。 同样，此问题可能是由于防火墙阻止了来自这些服务器的流量而导致的。 在这种情况下，可以采取两种做法：

  • 与 IT 部门协作，在 Microsoft 托管代理和 GitHub Enterprise Server 之间打开网络路径。 请参阅“Microsoft 托管代理”中有关网络的部分。

  • 改用自托管代理或规模集代理。 可以在网络中设置这些代理，从而使其可以访问 GitHub Enterprise Server。 这些代理只要求与 Azure Pipelines 建立出站连接。 无需为入站连接打开防火墙。 请确保在创建 GitHub Enterprise Server 连接时指定的服务器名称可从自托管代理解析。

Azure DevOps IP 地址

Azure Pipelines 将请求发送到 GitHub Enterprise Server，以便：

  • 在管道创建期间查询存储库列表（经典管道和 YAML 管道）
  • 在管道创建期间查找现有 YAML 文件（YAML 管道）
  • 签入 YAML 文件（YAML 管道）
  • 在管道创建期间注册 webhook（经典管道和 YAML 管道）
  • 为 YAML 文件提供编辑器（YAML 管道）
  • 在执行之前解析模板并展开 YAML 文件（YAML 管道）
  • 检查自上次计划的运行以来是否有任何更改（经典管道和 YAML 管道）
  • 提取有关最新提交的详细信息，并将其显示在用户界面（经典管道和 YAML 管道）

可以观察到，YAML 管道从根本上需要 Azure Pipelines 和 GitHub Enterprise Server 之间的通信。 因此，如果 GitHub Enterprise Server 对 Azure Pipelines 不可见，则无法设置 YAML 管道。

当使用“其他 Git”连接来设置经典管道、禁用 Azure Pipelines 服务与 GitHub Enterprise Server 之间的通信，并使用自托管代理生成代码时，获得的体验将会降级：

  • 必须在创建管道期间手动键入存储库的名称
  • 无法使用 CI 或 PR 触发器，因为 Azure Pipelines 无法在 GitHub Enterprise Server 中注册 Webhook
  • 无法将计划触发器与用于仅在发生更改时才执行生成的选项一起使用
  • 无法在用户界面中查看有关最新提交的信息

如果要设置 YAML 管道，或者想要增强经典管道的体验，请务必启用从 Azure Pipelines 到 GitHub Enterprise Server 的通信。

若要允许来自 Azure DevOps 的流量进入 GitHub Enterprise Server，请将入站连接中指定的 IP 地址或服务标记添加到防火墙的允许列表中。 如果使用 ExpressRoute，请务必将 ExpressRoute IP 范围也包含到防火墙的允许列表中。

限制

  • 为了获得最佳性能，建议单个存储库中最多 50 个管道。 为了获得可接受的性能，建议单个存储库中最多 100 个管道。 处理到存储库的推送所需的时间随着该存储库中管道数量的增加而增加。 每当推送到存储库时，Azure Pipelines 都需要加载该存储库中的所有 YAML 管道，以确定是否需要运行其中的任何管道，而加载每个管道会导致性能下降。 除了性能问题之外，单个存储库中有太多管道可能会导致 GitHub 端的限制，因为 Azure Pipelines 可能会在短时间内发出过多的请求。

  • 在管道中使用扩展和包含模板会影响 Azure Pipelines 发出 GitHub API 请求的速率，并可能导致 GitHub 端的限制。 在运行管道之前，Azure Pipelines 需要生成完整的 YAML 代码，因此需要提取所有模板文件。

  • Azure Pipelines 最多将存储库中的 2000 个分支加载到 Azure DevOps 门户的下拉列表中，例如为手动和计划生成的默认分支设置选择一个分支窗口，或者在手动运行管道的情况下在选择分支时这样做。

    如果在列表中看不到所需的分支，请在手动和计划生成的默认分支字段中手动键入所需的分支名称。

    如果单击省略号并打开选择分支对话框并关闭它，然后在不从下拉列表中选择有效分支的情况下将其关闭，你可能会在手动和计划生成的默认分支下方看到一些设置需要注意消息和该设置是必需设置消息。 若要解决此问题，请重新打开管道，并直接在手动和计划生成的默认分支字段中输入名称。

常见问题解答

与 GitHub Enterprise 集成相关的问题分为以下几个类别：

  • 触发器失败：将更新推送到存储库时，管道未触发。
  • 签出失败：管道正在触发，但在签出步骤中失败。
  • 版本错误：管道运行，但它使用的不是所需的源/YAML 版本。

触发器失败

我刚刚创建了一个包含 CI/PR 触发器的新 YAML 管道，但该管道未触发。

按照以下各步骤对失败的触发器进行故障排除：

  • 你的 YAML CI 或 PR 触发器是否被 UI 中的管道设置替代？ 编辑管道时，选择“...”，然后选择“触发器”。

    管道设置 UI。

    针对你的存储库可用的触发器类型（“持续集成”或“拉取请求验证”）选中“从此处替代 YAML 触发器”设置。

    从此处替代 YAML 触发器。

  • Webhook 用于将更新从 GitHub Enterprise 传达到 Azure Pipelines。 在 GitHub Enterprise 中，导航到存储库的设置，然后导航到 Webhook。 验证 Webhook 是否存在。 通常会看到两个 Webhook - push、pull_request。 如果没有，则必须重新创建服务连接，并更新管道以使用新的服务连接。

  • 在 GitHub Enterprise 中选择每个 Webhook，并验证与用户提交对应的有效负载是否存在以及是否已成功发送到 Azure DevOps。 如果无法将事件传达到 Azure DevOps，你可能会在此处看到错误。

  • 当 Azure Pipelines 收到来自 GitHub 的通知时，它会尝试联系 GitHub 并提取有关存储库和 YAML 文件的详细信息。 如果 GitHub Enterprise Server 位于防火墙后面，则此流量可能无法进入你的服务器。 请参阅 Azure DevOps IP 地址，并验证是否已为所有必需的 IP 地址授予例外。 自你最初设置例外规则以来，这些 IP 地址可能已更改。

  • 管道是否已暂停或禁用？ 打开管道的编辑器，然后选择“设置”进行检查。 如果管道已暂停或禁用，则触发器将不起作用。

  • 是否已在正确的分支中更新 YAML 文件？ 如果将更新推送到分支，则同一分支中的 YAML 文件将控制 CI 行为。 如果将更新推送到源分支，则因将源分支与目标分支合并而产生的 YAML 文件将控制 PR 行为。 请确保正确分支中的 YAML 文件具有必要的 CI 或 PR 配置。

  • 是否已正确配置触发器？ 定义 YAML 触发器时，可以为分支、标记和路径指定 include 和 exclude 子句。 确保 include 子句与提交的详细信息匹配，并且 exclude 子句不会排除它们。 检查触发器的语法，并确保它是正确无误的。

  • 是否在定义触发器或路径时使用了变量？ 这不受支持。

  • 是否对 YAML 文件使用了模板？ 如果是这样，请确保在主 YAML 文件中定义了触发器。 在模板文件中定义的触发器不受支持。

  • 是否排除了将更改推送到的分支或路径？ 通过将更改推送到包含的分支中包含的路径进行测试。 请注意，触发器中的路径区分大小写。 在触发器中指定路径时，请确保使用与真实文件夹相同的大小写。

  • 你刚刚推送了一个新分支吗？ 如果是这样，新分支可能不会启动新的运行。 请参阅“创建新分支时的触发器行为”。

我的 CI 或 PR 触发器一直工作正常。 但是，它们现在停止工作了。

首先，完成上一个问题中的故障排除步骤，然后执行以下附加步骤：

  • PR 中是否有合并冲突？ 对于未触发管道的 PR，请将其打开并检查它是否具有合并冲突。 解决合并冲突。

  • 是否在处理推送或 PR 事件时遇到延迟？ 通常可以通过查看该问题是特定于单个管道，还是适用于项目中所有管道或存储库来验证延迟。 如果对任何存储库的推送或 PR 更新都出现此症状，则可能是在处理更新事件时遇到延迟。 下面是可能发生延迟的一些原因：

    • 我们正在状态页上遇到服务中断。 如果状态页显示问题，则我们的团队必定已开始处理该问题。 请经常查看页面以获取有关该问题的更新。
    • 存储库包含的 YAML 管道过多。 为了获得最佳性能，建议单个存储库中最多 50 个管道。 为了获得可接受的性能，建议单个存储库中最多 100 个管道。 管道越多，处理到该存储库的推送的速度就越慢。 每当推送到存储库时，Azure Pipelines 都需要加载该存储库中的所有 YAML 管道，以确定其中是否有任何一个管道需要运行，并且每个新管道都会造成性能损失。
    • GitHub Enterprise Server 实例可能预配不足，从而减缓了从 Azure Pipelines 处理请求的速度。 详细了解 GitHub Enterprise Server 的硬件注意事项。

签出失败

是否使用了 Microsoft 托管代理？ 如果是，则这些代理可能无法访问 GitHub Enterprise Server。 有关详细信息，请参阅无法从 Microsoft 托管代理访问。

版本错误

管道中使用了错误的 YAML 文件版本。 为什么会这样？

  • 对于 CI 触发器，你所推送的分支中的 YAML 文件将受到评估，以了解是否应运行 CI 生成。
  • 对于 PR 触发器，因合并 PR 的源分支和目标分支而产生的 YAML 文件将受到评估，以了解是否应运行 PR 生成。