This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new a38f63109c [Improve][CI] Refine Merge Queue fallback and documentation
(#11970)
a38f63109c is described below
commit a38f63109caf84ef3188003142b3ff98e83e3062
Author: zhiwei.niu <[email protected]>
AuthorDate: Fri Aug 28 02:43:14 2026 +0000
[Improve][CI] Refine Merge Queue fallback and documentation (#11970)
---
.asf.yaml | 11 ++++---
.github/workflows/merge_queue.yml | 26 +++++----------
docs/en/developer/merge-queue.md | 66 +++++++++++++++++++++++++++++++++++++++
docs/sidebars.js | 1 +
docs/zh/developer/merge-queue.md | 66 +++++++++++++++++++++++++++++++++++++++
5 files changed, 147 insertions(+), 23 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
index 6986e38ef6..d146f3b201 100644
--- a/.asf.yaml
+++ b/.asf.yaml
@@ -13,7 +13,6 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
-
github:
description: SeaTunnel is a multimodal, high-performance, distributed,
massive data integration tool.
homepage: https://seatunnel.apache.org/
@@ -54,7 +53,11 @@ github:
- name: Merge Queue
target: branch
enforcement: active
- bypass_actors: []
+ bypass_actors:
+ # apache/root — ASF Infra team.
+ - actor_id: 118420
+ actor_type: Team
+ bypass_mode: always
conditions:
ref_name:
include:
@@ -63,8 +66,8 @@ github:
rules:
- type: merge_queue
parameters:
- # Leave time for runner scheduling and status reporting around the
30-minute job.
- check_response_timeout_minutes: 45
+ # Allow enough time for runner scheduling before the 30-minute job
starts.
+ check_response_timeout_minutes: 120
grouping_strategy: ALLGREEN
max_entries_to_build: 5
# Phase one merges each PR immediately instead of waiting to form
a batch.
diff --git a/.github/workflows/merge_queue.yml
b/.github/workflows/merge_queue.yml
index 17505af636..35b67320bb 100644
--- a/.github/workflows/merge_queue.yml
+++ b/.github/workflows/merge_queue.yml
@@ -44,24 +44,12 @@ jobs:
cache: maven
# Compile the standard modules with the CI profile.
- name: Compile main and test sources
- uses: nick-fields/retry@v3
- with:
- timeout_minutes: 28
- max_attempts: 3
- retry_wait_seconds: 10
- retry_on: error
- command: |
- ./mvnw -B -T 1C -Pci clean install -DskipTests \
- -D"license.skipAddThirdParty"=true -D"skip.ui"=true \
- --no-snapshot-updates
+ run: |
+ ./mvnw -B -T 1C -Pci clean install -DskipTests \
+ -D"license.skipAddThirdParty"=true -D"skip.ui"=true \
+ --no-snapshot-updates
# Build the opt-in seatunnel-benchmarks module with its dedicated
profile.
- name: Compile benchmark main and test sources
- uses: nick-fields/retry@v3
- with:
- timeout_minutes: 8
- max_attempts: 3
- retry_wait_seconds: 10
- retry_on: error
- command: |
- ./mvnw -B -Pbenchmark -pl seatunnel-benchmarks clean install
-DskipTests \
- -D"license.skipAddThirdParty"=true --no-snapshot-updates
+ run: |
+ ./mvnw -B -Pbenchmark -pl seatunnel-benchmarks clean install
-DskipTests \
+ -D"license.skipAddThirdParty"=true --no-snapshot-updates
diff --git a/docs/en/developer/merge-queue.md b/docs/en/developer/merge-queue.md
new file mode 100644
index 0000000000..4bb729ad4e
--- /dev/null
+++ b/docs/en/developer/merge-queue.md
@@ -0,0 +1,66 @@
+# Merge Pull Requests with Merge Queue
+
+SeaTunnel uses [GitHub Merge
Queue](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue)
for pull requests targeting `dev`. The queue validates a pull request against
the latest `dev` commit immediately before merge.
+
+## Add a Pull Request to the Queue
+
+1. Confirm that the pull request has the required approval and a successful
pull-request `Build`.
+2. Select **Merge when ready**.
+3. GitHub creates a temporary branch named like
`gh-readonly-queue/dev/pr-<number>-<sha>`.
+4. The `Merge Queue` workflow runs the required `Build` against that temporary
commit.
+5. If the build succeeds, GitHub squash-merges the pull request into `dev`.
+
+The queue build compiles the standard Maven reactor with the `ci` profile and
then compiles `seatunnel-benchmarks` with the `benchmark` profile. Both
commands use `-DskipTests`: tests are not executed, but main and test sources
are compiled.
+
+## Find Why a Pull Request Left the Queue
+
+When a required check fails, times out, or the temporary commit conflicts with
`dev`, GitHub removes the pull request from the queue and records the reason in
the pull request timeline.
+
+1. Open the pull request and find the merge-queue removal event in the
timeline.
+2. Follow the failed `Build` or **Details** link to the workflow run.
+3. If the timeline does not provide a run link, open **Actions** in
`apache/seatunnel`, select **Merge Queue**, and find the run whose branch
contains `pr-<pull-request-number>-`.
+4. Open the `Build` job and expand the failed step:
+ - `Compile main and test sources`
+ - `Compile benchmark main and test sources`
+5. Search the log for the first Maven `[ERROR]` or `BUILD FAILURE`. The final
`Process completed with exit code 1` line only reports the result; the useful
cause normally appears earlier.
+
+If the browser view is truncated or difficult to search, use **Download log
archive** from the run page. With GitHub CLI, print only failed logs with:
+
+```shell
+gh run view <run-id> --repo apache/seatunnel --log-failed
+```
+
+## Classify the Failure
+
+| Log signal | Likely cause | Next action |
+| --- | --- | --- |
+| `COMPILATION ERROR`, `cannot find symbol`, `incompatible types`, or `method
... cannot be applied` | The queued commit does not compile with the latest
`dev` | Fix the code or rebase the pull request |
+| `Could not transfer artifact`, `Connection reset`, `Read timed out`, or an
HTTP 403/429/5xx response | Maven repository or network failure | Confirm that
no compilation error occurred, then requeue |
+| The job reaches the 30-minute limit or is cancelled while a Maven step is
still running | Runner, dependency download, or unexpectedly slow build | Check
the last active step; investigate repeated timeouts before requeueing |
+| No `Merge Queue` run starts, or the required `Build` remains pending until
the queue timeout | Queue event, runner scheduling, or status-reporting problem
| Check whether a `merge_group` run was created and whether the required check
is linked to that run; preserve the pull request and run links for further
investigation |
+| The pull request timeline reports a base-branch conflict or
branch-protection failure | The temporary commit no longer satisfies merge
requirements | Update or rebase the pull request and complete the required
checks again |
+
+## Recover and Requeue
+
+- For a code or compatibility failure, push the fix or rebase onto the latest
`dev`. Wait for the pull-request checks and any required approval to pass
again, then select **Merge when ready**.
+- For a confirmed temporary infrastructure failure, select **Merge when
ready** again without changing the code.
+- Do not repeatedly requeue an unknown failure. Save the PR URL, workflow run
URL, failed step, and the first relevant error when asking the community for
help.
+- Re-running an old workflow run does not add an ejected pull request back to
the queue; requeue it from the pull request after the cause has been handled.
+
+If an earlier queue entry fails, GitHub rebuilds later temporary groups
without that entry. No manual action is required for those later pull requests
unless their own checks fail.
+
+## Last-resort Recovery When Merge Queue Remains Unavailable
+
+When Merge Queue itself fails and the troubleshooting and recovery steps above
do not restore its ability to queue or merge an otherwise mergeable pull
request, ASF Infra may use the `apache/root` team bypass as a last-resort
recovery path.
+
+The bypass mode is `always`, so it applies to both pull-request merges and
direct pushes for this ruleset; separate branch-protection rules are evaluated
independently.
+
+:::warning Use only when normal recovery has failed
+
+This bypass is not an alternative merge path. It must not be used to skip
normal queue waiting, required approval, a failed `Build`, or a compilation
problem.
+
+Preserve the pull request and workflow-run links when contacting ASF Infra.
Whenever possible, recovery should use a reviewed pull request with a
successful normal `Build`; direct push should remain a last resort.
+
+Bypassing Merge Queue removes its exact-combination validation and may make
active merge groups stale. After recovery, verify the new `dev` commit with the
same Maven compile commands or an equivalent post-merge build, and monitor
queued pull requests for automatic rebuilds or failures.
+
+:::
diff --git a/docs/sidebars.js b/docs/sidebars.js
index a986edc575..57c1fe4bd9 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -394,6 +394,7 @@ const sidebars = {
"developer/setup",
"developer/contribution-path",
"developer/coding-guide",
+ "developer/merge-queue",
"developer/test-coding-guide",
"developer/shade-guide",
"developer/how-to-create-your-connector",
diff --git a/docs/zh/developer/merge-queue.md b/docs/zh/developer/merge-queue.md
new file mode 100644
index 0000000000..4de96cd84a
--- /dev/null
+++ b/docs/zh/developer/merge-queue.md
@@ -0,0 +1,66 @@
+# 使用 Merge Queue 合并 Pull Request
+
+SeaTunnel 对目标分支为 `dev` 的 Pull Request 启用了 [GitHub Merge
Queue](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue)。队列会在合并前，基于最新的
`dev` 再次验证 PR。
+
+## 将 Pull Request 加入队列
+
+1. 确认 PR 已获得所需批准，并且 PR 自身的 `Build` 成功。
+2. 选择 **Merge when ready**。
+3. GitHub 会创建名称类似 `gh-readonly-queue/dev/pr-<number>-<sha>` 的临时分支。
+4. `Merge Queue` workflow 会对这个临时提交运行必需的 `Build`。
+5. 构建成功后，GitHub 会将 PR squash merge 到 `dev`。
+
+队列构建首先使用 `ci` profile 编译标准 Maven reactor，然后使用 `benchmark` profile 编译
`seatunnel-benchmarks`。两个命令都使用 `-DskipTests`：测试不会执行，但 main 和 test 源码仍会编译。
+
+## 查看 Pull Request 被移出队列的原因
+
+必需检查失败或超时，或者临时提交与 `dev` 冲突时，GitHub 会将 PR 移出队列，并在 PR timeline 中记录原因。
+
+1. 打开 PR，在 timeline 中找到被移出 Merge Queue 的事件。
+2. 通过失败的 `Build` 或 **Details** 链接进入 workflow run。
+3. 如果 timeline 中没有 run 链接，进入 `apache/seatunnel` 的 **Actions**，选择 **Merge
Queue**，查找分支名包含 `pr-<PR编号>-` 的 run。
+4. 打开 `Build` job，并展开失败的步骤：
+ - `Compile main and test sources`
+ - `Compile benchmark main and test sources`
+5. 在日志中搜索第一个 Maven `[ERROR]` 或 `BUILD FAILURE`。最后的 `Process completed with
exit code 1` 只表示执行失败，真正的原因通常在它之前。
+
+如果网页日志被截断或不方便搜索，可以在 run 页面选择 **Download log archive**。也可以使用 GitHub CLI 只查看失败日志：
+
+```shell
+gh run view <run-id> --repo apache/seatunnel --log-failed
+```
+
+## 判断失败类型
+
+| 日志特征 | 可能原因 | 处理方式 |
+| --- | --- | --- |
+| `COMPILATION ERROR`、`cannot find symbol`、`incompatible types` 或 `method ...
cannot be applied` | 当前队列提交无法与最新 `dev` 一起编译 | 修复代码或对 PR 执行 rebase |
+| `Could not transfer artifact`、`Connection reset`、`Read timed out` 或 HTTP
403/429/5xx | Maven 仓库或网络故障 | 确认没有编译错误后重新入队 |
+| Job 达到 30 分钟限制，或者在 Maven 步骤仍在运行时被取消 | Runner、依赖下载或构建耗时异常 |
查看最后执行的步骤；重复超时时应先排查，不要直接重新入队 |
+| 没有触发 `Merge Queue` run，或者必需的 `Build` 一直 pending 直到队列超时 | 队列事件、Runner
调度或状态上报异常 | 检查是否生成 `merge_group` run、required check 是否关联到该 run，并保留 PR 和 run
链接以便进一步排查 |
+| PR timeline 提示与目标分支冲突或分支保护失败 | 临时提交不再满足合并要求 | 更新或 rebase PR，并重新完成必需检查 |
+
+## 修复并重新入队
+
+- 如果是代码或兼容性问题，请提交修复或基于最新 `dev` 执行 rebase。等待 PR 检查和所需批准再次通过后，选择 **Merge when
ready**。
+- 如果已经确认是临时基础设施故障，可以不修改代码，直接再次选择 **Merge when ready**。
+- 不要对原因不明的失败反复重新入队。向社区求助时，请提供 PR URL、workflow run URL、失败步骤和第一个有效错误。
+- 重新运行旧的 workflow run 不会让已被移出的 PR 重新进入队列；处理完失败原因后，需要回到 PR 页面重新入队。
+
+如果较早的队列条目失败，GitHub 会排除该条目并重新构建后续临时 merge group。除非后续 PR 自身的检查也失败，否则不需要人工处理。
+
+## Merge Queue 无法恢复时的应急处理
+
+当 Merge Queue 本身发生故障，并且按照上述排查和恢复步骤处理后，仍然无法让一个原本满足合并条件的 PR 正常入队或合并时，ASF Infra
可以使用 `apache/root` team 的 bypass 作为最后恢复手段。
+
+bypass mode 为 `always`，因此对该 Ruleset 的 Pull Request 合并和直接 push
均适用；其他独立的分支保护规则仍会分别检查。
+
+:::warning 仅在常规恢复无效时使用
+
+此 bypass 不是另一种日常合并方式。不得用它跳过正常排队、必需的批准、失败的 `Build` 或编译问题。
+
+联系 ASF Infra 时，请保留 PR 和 workflow run 链接。只要条件允许，应通过已经 review 且普通 `Build` 成功的 PR
完成恢复；直接 push 只能作为最后手段。
+
+绕过 Merge Queue 会失去最终代码组合验证，也可能让正在运行的 merge group 失效。恢复后，应使用相同的 Maven 编译命令或等价的
post-merge build 验证新的 `dev` 提交，并关注队列中的 PR 是否自动重新构建或失败。
+
+:::
