c88d59d2创建于 13 天前历史提交

pr-sync-action

黄蓝协同插件 · 触发 PR 同步 + 回显 MR 门禁结果

功能：用户在 GitCode 提交 PR 或发表评论后，代码同步到黄区 CodeHub 并触发 MR 门禁流水线；插件负责按需触发同步、轮询同步结果，并把结果回显到 GitCode PR 页（PR 标签 + 任务结果页）
架构变化：同步主链路（webhook → openlibing → MQS → libing → 云龙 → CodeHub）保持不变；结果回显路径由「黄区 libing 直写 GitCode（评论 + 标签）」改为「GitCode 插件轮询 APIG 获取结果 → 任务结果页结构化展示 + 回写 PR 标签」

1. 简介

1.1 黄蓝协同

背景

蓝区：代码托管在 GitCode、GitHub 平台，外部贡献者在蓝区发起 PR。
黄区：代码仓为 CodeHub，门禁 / 构建流水线在内网执行，受密级管控。
协同诉求：外部贡献者在蓝区发起的 PR，需要自动进入黄区跑 MR 门禁流水线，且以 PR 页可见的方式反馈结果。

功能

一句话：PR / 评论触发 → 代码同步到黄区 CodeHub → 触发 MR 门禁流水线 → 结果回显 GitCode PR 页（标签 + 结果）。

1.2 pr-sync-action 插件

背景

结果回显原本由黄区服务（libing）在同步结束后直写 GitCode（评论 + 标签），由此带来三个问题：

#	痛点	说明
P1	黄区直连 git 平台	libing 与 GitCode API 强耦合，直接回写同步结果到 PR；如果要修改评论或者标签的内容，就需要修改代码
P2	展示形态单一	结果只有「评论 + 标签」两种形态
P3	排查困难	同步触发失败时用户无法感知，PR 页面没有任何数据展示；排障需要跨 GitCode / openlibing / libing / 云龙流水线四处翻日志

功能

把「结果回显」从 libing 服务操作改到 GitCode 流水线插件执行：

按需触发 PR 同步 —— 通过在 PR 输入指定评论，可重新触发一轮同步；
支持回写 PR 标签 —— 支持在 PR 中写入执行中 / 成功 / 失败三种状态标签，支持自定义标签内容；
结构化展示 —— 任务结果页输出结果（中文）、目标仓库MR链接、同步任务详情链接。

2. 方案架构设计

2.1 架构图

新方案有两条并行的入口线路，触发机制不同，都终止于蓝区 openlibing，其后是同一条同步主链路：

入口一 · GitCode webhook：用户创建 PR / 提交 commit 时触发，自动同步代码与 PR；
入口二 · GitCode Action：用户在 PR 下发表评论时触发插件流水线，用于手动重新触发 PR 同步；插件经 openlibing 平台触发 PR 同步、轮询同步结果并回写标签。

flowchart TD
    U["用户"] -->|"创建 PR / 提交 commit"| WH["GitCode webhook"]
    U -->|"发表 PR 评论"| GA["GitCode Action"]
    U ~~~ GC["GitCode"]

    WH -->|"线路一 · 触发 PR 同步"| OL["蓝区 openlibing 服务"]
    GA -->|"线路二 · 运行插件流水线"| ACT["pr-sync-action 插件"]
    ACT -->|"触发 PR 同步"| OL

    OL -->|"① MQS 消息"| LIB["黄区 libing 服务"]
    LIB -->|"② 触发"| YL["云龙流水线"]
    YL -->|"③ 同步 PR"| CH["CodeHub 代码仓"]
    CH -->|"④ 触发"| MR["MR 流水线"]
    LIB -->|"⑤ 获取 MR 流水线结果"| MR
    LIB -.->|"⑥ 回写同步结果"| OL
    ACT -.->|"⑦ 轮询同步结果"| OL
    ACT -.->|"⑧ 回写 PR 标签"| GC
    GC -.->|"⑨ 结果展示（PR 页）"| U

2.2 完整时序

sequenceDiagram
    autonumber
    participant U as 用户
    participant GC as GitCode
    participant OL as 蓝区 openlibing
    participant YL as 黄区 libing / 云龙
    participant CH as CodeHub
    participant ACT as pr-sync-action 插件

    U->>GC: 创建 PR / 提交 commit
    par 线路一 · webhook → openlibing（与线路二并行，无先后）
        GC->>OL: webhook 触发同步
        OL->>YL: MQS 消息
        YL->>CH: 云龙流水线同步 PR
        CH->>CH: 触发 MR 流水线
        YL->>CH: 获取 MR 流水线结果
        YL-->>OL: 结果回写 openlibing
    and 线路二 · Action → openlibing（触发 / 轮询 + 回写展示）
        U->>GC: 发表 PR 评论（如 compile#openlibing）
        GC->>ACT: 评论事件触发插件流水线
        ACT->>OL: 按需触发 PR 同步（新增能力，经 APIG）
        loop 轮询直至终态（默认 60s 间隔、1h 总超时）
            ACT->>OL: POST cross-region/v1/pipelineInfo（经 APIG 网关，owner/repo/platform/prNumber）
            OL-->>ACT: 同步状态 / 错误码 / MR 链接 / 构建详情；无记录返回 null
            ACT->>GC: 状态变化时才落标签（RUNNING → 执行中标签，去重）
        end
        ACT->>GC: ⑦ 补写终态标签 SC-SUCC / SC-FAIL（并清理其余状态标签与历史 SC-*）
        ACT->>GC: ⑧ 写任务结果页（结果 / 目标仓库MR链接 / 同步任务详情链接）
        GC-->>U: PR 标签与任务结果页可见
    end

2.3 与原方案差异对照

维度	原方案	新方案（引入 Action 插件）
同步结果展示方式	黄区 libing 直接写到 GitCode 的评论中	Git 插件从 openlibing 平台获取结果
结果展示形态	PR 评论 + 标签	GitCode Action 的任务结果页 + PR 标签
错误信息	无失败原因	错误码 + 错误描述 + 修复建议 + 构建详情链接

3. 原方案功能效果页面（无Action 插件）

原方案的功能页面即 libing 直写回 GitCode 的 PR 评论与标签：

3.1 PR 评论（同步结果通知）

原方案 PR 评论

3.2 PR 标签（同步状态）

原方案 PR 标签

3.3 跳转目标仓 PR 详情

原方案跳转目标仓 PR 详情页面

4. 新方案功能配置与结果展示（使用 Action 插件）

PR 页流水线

PR 页流水线

插件运行页面

插件运行页面

插件结果页面

插件结果页面

4.1 插件使用方式（编排 yml）

最小可用编排（所有输入参数均有默认值，with: 可完全留空）：

name: 代码仓 PR 同步

on:
  pull_request_target: # PR 打开 / 更新时自动触发
    branches: [main]
  pull_request_comment: # PR 下评论关键词 → 手动重新触发
    types: [created]
    comments: ["compile#openlibing"] # 关键词可按需自定义
    branches: [main]

permissions:
  repository: read
  pr: write # 回写 PR 标签的必要权限
  id-token: write # OIDC 免密换证的必要权限

jobs:
  sync:
    name: 同步结果
    runs-on: ["codearts-hosted", "ubuntu-latest", "x64", "small"]
    steps:
      - name: 同步结果
        uses: openlibing/pr-sync-action@v1.0.0

完整编排（全部可用参数）：

name: 代码仓 PR 同步

on:
  pull_request_target: # PR 打开 / 更新时自动触发
    branches: [main]
  pull_request_comment: # PR 下评论关键词 → 手动重新触发
    types: [created]
    comments: ["compile#openlibing"] # 关键词可按需自定义
    branches: [main]

permissions:
  repository: read
  pr: write # 回写 PR 标签的必要权限
  id-token: write # OIDC 免密换证的必要权限（推荐）

jobs:
  sync:
    name: 同步结果
    runs-on: ["codearts-hosted", "ubuntu-latest", "x64", "small"]
    steps:
      - name: 同步结果
        id: sync # 步骤 id，供后续步骤引用 outputs
        uses: openlibing/pr-sync-action@v1.0.0
        with:
          # ── 轮询行为 ──
          poll_interval_seconds: "60" # 轮询间隔（秒），建议 ≥30 防网关限流
          poll_timeout_seconds: "3600" # 轮询总超时（秒），按同步流水线最长耗时调整
          # ── 结果与开关 ──
          ignore_failure: "false" # true：失败 / 超时不阻断流水线；false：阻断后续步骤
          # ── PR 标签 ──
          label_enabled: "false"
          running_label: "SC-RUNNING"
          success_label: "SC-SUCC"
          failure_label: "SC-FAIL"

4.2 插件名称

mr门禁结果获取插件 · pr-sync-action

4.3 输入参数

参数	必填	默认值	说明
`poll_interval_seconds`	否	`60`	轮询间隔（秒）；建议 ≥30 防网关限流
`poll_timeout_seconds`	否	`3600`	轮询总超时（秒）
`ignore_failure`	否	`false`	同步失败 / 超时是否阻断插件运行；配置为 `true` 时，即使同步失败，插件流水线仍显示为运行成功
`label_enabled`	否	`false`	是否回写 PR 标签
`running_label`	否	`SC-RUNNING`	执行中标签文案（≤50 字符、不含逗号 / 换行）
`success_label`	否	`SC-SUCC`	成功标签文案
`failure_label`	否	`SC-FAIL`	失败标签文案

4.4 运行结果页

轮询结束后任务结果页展示以下键值对：

键	示例值
结果	`成功` / `失败` / `超时` / `跳过` / `无记录`
目标仓库MR链接	`https://…/merge_requests/127`，点击跳转目标仓 MR
同步任务详情链接	`https://…/buildProjectDetail/…`，点击跳转目标仓同步流水线详情

错误码、错误描述、修复建议与耗时仅在插件执行日志中输出，不占用任务结果页。

5. 相关配置清单

接入前需完成以下四项配置：

#	配置位置	配置内容
1	openlibing 平台 · 代码仓管理	录入 GitCode 代码仓
2	libing 平台 · 代码仓管理 → 代码仓同步	录入 GitCode 代码仓与 CodeHub 代码仓的映射关系
3	GitCode / CodeHub 代码仓 · 成员角色	GitCode 代码仓添加 `openLibingCI` 角色；CodeHub 代码仓添加 `p_LibingCI` 角色
4	GitCode 代码仓 · workflow	创建 workflow 文件，指定 action 流水线使用 `pr-sync-action` 插件（编排示例见 4.1）

四项配置完成后：PR 打开 / 提交 commit 由 webhook 触发同步主链路；PR 评论触发插件流水线，插件按需触发同步并轮询回显结果（见 2.1 架构图）。