setup-darc-branch-publishing

用途

该技能用于将 .NET 仓库的某个分支配置为通过 Maestro 频道（例如 General Testing）发布官方构建产物。配置完成后，该分支的官方构建会将资产注册到 BAR（Build Asset Registry），并通过指定频道进行发布。

主要能力

确认目标仓库与分支，避免误配同名分支。
列出并确认 Maestro 频道及现有默认频道关联，检查是否已存在相同关联以避免重复。
检查仓库的官方构建流水线及其构建后发布配置（如 publish-build-assets、post-build.yml、PromoteToChannel 等）。
通过 Darc 添加分支到频道的默认关联。
在官方流水线 YAML 的 trigger.branches.include 中添加目标分支，使官方构建在该分支上触发。
向仓库默认分支提交持久化的流水线触发器变更 PR。
验证关联是否生效、目标分支是否包含触发器、默认分支 PR 是否包含持久配置，以及后续官方构建是否注册到 BAR 并提升到指定频道。

使用方式

前置条件

已安装 darc 并完成 Maestro 认证。
已安装 gh 并完成源仓库认证。
Azure CLI 已认证到 dnceng Azure DevOps 组织。
用户具有更新目标分支和针对仓库默认分支创建 PR 的权限。

阶段一：收集信息

确认确切的仓库和分支，检查上游仓库和用户 fork：

git remote -v
git ls-remote --heads upstream "refs/heads/<branch>"
gh api "repos/<owner>/<repo>/branches/<url-encoded-branch>"

如果请求的分支不存在但存在同名分支，需询问用户选择哪个分支。

查找频道和既有配置：

darc get-channels --output-format json
darc get-default-channels \
  --source-repo "https://github.com/<owner>/<repo>" \
  --output-format json

确认请求的频道存在，并查找是否已有其他实验分支使用该频道。在添加前检查是否已存在完全相同的仓库、分支和频道关联，避免重复创建。

检查仓库发布配置：

rg -n "trigger:|publish-build-assets|post-build.yml|PromoteToChannel" \
  azure-pipelines*.yml eng

对于 Roslyn：

azure-pipelines-official.yml 控制哪些分支触发官方构建。
现有的 Arcade publish-build-assets.yml 和 post-build.yml 钩子将资产注册到 BAR 并将构建提升到默认频道。
eng/Publishing.props 控制包元数据，通常无需针对分支修改。
不要编辑 eng/common，它由 Arcade 管理。

分支必须包含在官方流水线触发器中。Azure Pipelines 会评估正在构建的分支上的 YAML，因此应在目标分支上进行触发器更改以立即生效，并将相同更改提交到默认分支作为持久仓库配置。

阶段二：规划

呈现以下计划操作：

通过 Darc 添加分支到频道的默认关联。
在目标分支的官方流水线触发器中添加该分支。
仅在获得明确许可后推送目标分支更改。
向仓库默认分支提交相同的流水线更改以及任何工作流文档更新。
报告 Maestro 配置 PR，该 PR 必须合并后关联才会生效。

在继续之前获得用户明确确认。

阶段三：执行

添加 Darc 默认频道：

darc add-default-channel \
  --channel "<channel>" \
  --branch "<branch>" \
  --repo "https://github.com/<owner>/<repo>" \
  --quiet

如果 Darc 无法读取 GitHub 分支，传入已认证的 GitHub token 但不打印：

darc add-default-channel \
  --channel "<channel>" \
  --branch "<branch>" \
  --repo "https://github.com/<owner>/<repo>" \
  --quiet \
  --github-pat "$(gh auth token)"

如果 Maestro 配置仓库返回 HTTP 401，获取 Azure DevOps 资源的访问令牌并直接传入：

AZDO_TOKEN="$(
  az account get-access-token \
    --resource 499b84ac-1321-427f-aa17-267ca6975798 \
    --query accessToken \
    --output tsv
)"

darc add-default-channel \
  --channel "<channel>" \
  --branch "<branch>" \
  --repo "https://github.com/<owner>/<repo>" \
  --quiet \
  --github-pat "$(gh auth token)" \
  --azdev-pat "$AZDO_TOKEN"

不要为 add-default-channel 添加 --output-format json，该操作不支持 JSON 输出。

记录生成的 Maestro 配置 PR URL。在该 PR 合并之前，频道关联不会生效。

在目标分支上启用官方构建：

在官方流水线 YAML 的 trigger.branches.include 下添加确切分支。进行最小可能的更改并验证：

git diff --check
git diff -- azure-pipelines-official.yml

仅在获得用户明确许可后提交并推送。

创建持久的默认分支 PR：

从最新的上游默认分支创建新分支。应用相同的官方流水线触发器更改，并包含用户要求的任何工作流文档或技能更新。

验证差异，使用仓库要求的提交尾注提交，在获得明确许可后推送到用户 fork，并向上游默认分支打开 PR。

不要发布 PR 评论、审查或回复。向用户提供 PR URL。

验证

在 Maestro 配置 PR 合并后，验证关联：

darc get-default-channels \
  --source-repo "https://github.com/<owner>/<repo>" \
  --branch "<branch>" \
  --channel "<channel>" \
  --output-format json

验证以下内容：

关联存在且已启用。
目标分支包含官方流水线触发器。
默认分支 PR 包含持久触发器配置。
后续官方构建注册到 BAR 并提升到请求的频道。

错误处理

分支名称不匹配：停止并让用户选择确切分支。
已存在关联：不要添加重复项。
GitHub HTTP 401：使用 --github-pat "$(gh auth token)" 重试。
Azure DevOps HTTP 401：使用 Azure DevOps 资源访问令牌重试。
Maestro 配置 PR 未合并：报告发布尚未生效。
缺少官方发布钩子：停止并在更改 Darc 之前调查仓库的 Arcade 发布设置。

适用场景

需要将 .NET 仓库的某个分支（如实验分支）的官方构建产物发布到 General Testing 或其他 Maestro 频道。
需要为分支建立 BAR 资产注册和频道提升的持久配置。

限制

该工作流会创建 Maestro 配置仓库 PR 并修改仓库的官方流水线触发器，执行前必须获得用户明确确认。
未经用户明确许可，不得推送仓库分支。
频道关联在 Maestro 配置 PR 合并前不会生效。
不要编辑 eng/common，它由 Arcade 管理。
不要为 add-default-channel 添加 --output-format json。
不要发布 PR 评论、审查或回复。
需要 darc、gh、Azure CLI 的安装与认证，以及相应的仓库和 Azure DevOps 权限。