Homepage 集成 Azure DevOps WidgetPipeline 运行状态与 Pull Request 看板配置指南【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageHomepage 是一个高度可定制的主页起始页 / 应用仪表盘项目通过服务 API 集成能力将各类自托管与云服务的状态直接呈现在首页。本指南聚焦其中的Azure DevOps Widget讲解如何利用个人访问令牌PAT对接 Azure DevOps REST API在 Homepage 上同时展示 Pipeline 的最近构建结果与 Pull Request 的聚合统计。读完本文你将掌握该 Widget 的完整配置项、两种数据功能的启用条件以及其底层 API 调用与前端渲染的实现原理。功能总览一个 Widget两类数据Azure DevOps Widget 在 docs/widgets/services/azuredevops.md 中明确定义了两个核心功能Pipelines流水线检查指定 Pipeline 当前是否在运行如果不在运行则报告最近一次构建的结果。该功能展示的字段为[result, status]。Pull Requests拉取请求返回三类聚合数据——仓库中打开Open的 PR 总数、由你本人打开的 PR 数量以及由你打开、且已被至少 1 人标记为Approved批准且尚未合并完成的 PR 数量。该功能展示的字段为[totalPrs, myPrs, approved]。两个功能可以独立使用也可以同时启用。是否启用 PR 功能完全由配置决定详见下文而 Pipeline 功能在配置了definitionId后始终生效。前置条件生成 Azure DevOps 个人访问令牌Widget 通过 Azure DevOps 官方 REST API 拉取数据因此必须为某个已有用户生成一个个人访问令牌Personal Access TokenPAT并在 Homepage 的配置中以key字段传入。生成 PAT 时需要为该令牌授予访问 Build流水线与 Pull Requests 相关资源所需的权限范围通常为 Build (Read) 与 Code (Read) 即可满足只读展示需求。在 Homepage 侧该令牌只会被用于服务端代理请求见下文认证实现一节不会直接暴露给浏览器端因此可以放心使用具备只读权限的最小化令牌。完整配置示例与参数说明在 Homepage 的services.yaml或按分组书写的widgets.yaml中为某个服务条目添加如下 widget 配置完整配置与 widget 官方文档 保持一致widget: type: azuredevops organization: myOrganization project: myProject definitionId: pipelineDefinitionId # required for pipelines branchName: branchName # optional for pipelines, leave empty for all userEmail: email # required for pull requests repositoryId: prRepositoryId # required for pull requests key: personalaccesstoken各参数的职责与生效条件整理如下参数是否必填适用功能说明type必填全部固定为azuredevops用于注册 widget 类型organization必填全部Azure DevOps 组织名称URL 中的组织段project必填全部项目名称URL 中的项目段definitionIdPipeline 必填PipelinesPipeline 定义 ID用于定位要监控的流水线branchName可选Pipelines分支名称过滤留空表示展示所有分支的最近构建userEmailPR 必填Pull Requests你的登录邮箱用于在返回的 PR 列表中筛选我的 PRrepositoryIdPR 必填Pull Requests仓库 IDGUID 或名称决定统计哪个仓库的 PRkey必填全部Azure DevOps 个人访问令牌PAT启用规则重要从 component.jsx 的源码可以确认只有userEmail与repositoryId同时存在时PR 数据请求才会被发起includePR userEmail ! undefined repositoryId ! undefined对应的totalPrs、myPrs、approved三个统计块才会渲染。若仅需 Pipeline 功能省略这两个字段即可此时页面只展示 Pipeline 的状态/结果块。源码级原理API 端点与占位符替换Widget 的 API 定义集中在 src/widgets/azuredevops/widget.js其基础 URL 为https://dev.azure.com/{organization}/{project}/_apis/{endpoint}并通过mappings声明了两个端点模板映射名endpoint 模板用途prgit/repositories/{repositoryId}/pullrequests拉取指定仓库的 PR 列表pipelinebuild/Builds?branchName{branchName}definitions{definitionId}拉取指定定义的构建记录这些{占位符}在请求发出前由 src/utils/proxy/api-helpers.js 中的formatApiCall函数完成替换它以正则匹配花括号内的键名从 widget 配置中取出对应值如organization、project、definitionId逐一填入。因此配置项名称与端点模板中的占位符必须严格一致例如definitionId对应{definitionId}、branchName对应{branchName}。可以推断Pipeline 数据请求最终形如https://dev.azure.com/{organization}/{project}/_apis/build/Builds?branchName{branchName}definitions{definitionId}而 PR 数据请求最终形如https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequestsbranchName留空时URL 中对应的查询参数为空字符串即不做分支过滤展示该定义下所有分支的最近构建。认证实现PAT 如何随请求发出所有 Homepage 的服务 widget 请求都经由服务端代理转发避免在前端暴露令牌。Azure DevOps 的认证处理位于 src/utils/proxy/handlers/credentialed.js} else if (widget.type azuredevops) { headers.Authorization Basic ${Buffer.from($:${widget.key}).toString(base64)}; }即对azuredevops类型代理层会把keyPAT构造成HTTP Basic 认证头——用户名固定为$、密码为 PAT整体做 Base64 编码后放入Authorization请求头。这是 Azure DevOps REST API 官方支持的 PAT 认证方式。因此key字段必须填写有效的 PAT否则 API 会返回 401 未授权错误。代理层随后通过httpProxy向 Azure DevOps 发起请求src/utils/proxy/handlers/credentialed.js并对返回数据做统一校验与错误处理非 2xx 状态会携带脱敏后的 URL 返回错误信息200 响应则会经过validateWidgetData的数据结构校验后再返回给前端。前端渲染Pipeline 与 PR 三个统计块前端组件 src/widgets/azuredevops/component.jsx 使用useWidgetAPI分别请求pr与pipeline两个端点渲染逻辑如下Pipeline 状态展示取构建记录列表的第一条pipelineData.value[0]。若该记录存在result字段则显示结果Result否则显示状态Status。结合 public/locales/en/common.json 中的翻译项可展示的值包括succeeded成功、failed失败、canceled已取消、notStarted未开始、inProgress进行中等。这正是文档所说的检查 Pipeline 是否在运行若不在则报告最近一次结果——inProgress对应正在运行其他值对应已完成或待启动的最近结果。PR 三个统计块仅当includePR为真时渲染totalPrs取响应中的count字段即当前仓库打开 PR 的总数myPrs从 PR 列表中筛选createdBy.uniqueName不区分大小写等于userEmail的条目数量approved在上一步筛选结果的基础上再过滤出reviewers数组中至少有一位评审人投票值vote为 5 或 10的 PR 数量。在 Azure DevOps 的评审投票约定中vote 10表示已批准Approvedvote 5表示带建议批准Approved with suggestions二者均计入被批准统计。userEmail的比较是大小写不敏感的toLowerCase()归一化因此配置邮箱时大小写均可。错误处理与降级表现组件对两类请求的错误做了分级处理src/widgets/azuredevops/component.jsx若 Pipeline 请求失败或 PR 请求失败且返回了errorCode页面会显示错误容器并优先采用 PR 侧更具体的错误消息如Bad PR作为展示文案若数据尚未就绪则渲染 4 个占位块result、totalPrs、myPrs、approvedPR 调用返回errorCode但未附带 message 时兜底文案为 Error communicating with Azure API。以上行为均被 src/widgets/azuredevops/component.test.jsx 中的测试用例覆盖包括加载占位、仅 Pipeline 渲染、PipelinePR 联合渲染验证myPrs按邮箱过滤、approved按 reviewer vote 过滤以及 PR 错误码时的错误消息展示。若你在配置后遇到问题可结合这些场景逐一排查PAT 权限是否包含 Build/Code 只读、definitionId与repositoryId是否正确、userEmail是否与账号唯一名一致等。小结Azure DevOps Widget 以一段 YAML 配置即可在 Homepage 首页同时呈现 Pipeline 的最近构建状态与仓库 PR 的聚合看板。其实现要点可归纳为widget.js声明 REST 端点模板、credentialed代理处理器完成 PAT 的 Basic 认证注入、前端组件按配置决定是否启用 PR 统计并完成邮箱与评审投票的二次筛选。按上文参数表补全organization、project、definitionIdPipeline或userEmailrepositoryIdPR以及key你的 Azure DevOps 状态即可无缝融入 Homepage 仪表盘。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考