Skip to content

Commit 7b81ab1

Browse files
cdeustclaude
andauthored
ci: the review's completion wakes the resolver as the Pipeline's does (ADR-1127) (#958)
The resolver ran once, on the Pipeline's completion. A review that ended after the Pipeline left the PR unmerged with an approve. pipeline-after-merge.yml now listens to PR Review as well; woken by a review, the resolver resolves the newest successful Pipeline run of that head and applies the same checks. Claude-Session: https://claude.ai/code/session_018kyZYsWnKSjpX4oNV19PCF Co-authored-by: Claude <[email protected]>
1 parent b5a50aa commit 7b81ab1

9 files changed

Lines changed: 235 additions & 4 deletions

‎.github/workflows/pipeline-after-merge.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@ name: Pipeline after merge
44
# GitHub rejects a workflow listening to itself (run40017492191).
55
# The local reusable retains this caller's workflow_run event context.
66
# https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations#github-context
7+
# The review and the Pipeline finish in either order: each completion wakes the
8+
# resolver, which merges once both are there (ADR-1127).
79
on:
810
workflow_run:
9-
workflows: [Pipeline]
11+
workflows: [Pipeline, PR Review]
1012
types: [completed]
1113
branches-ignore: [main]
1214

‎.github/workflows/pipeline-post-merge.yml‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,43 @@ jobs:
228228
return list(indexed.values())
229229
230230
231+
# source: .github/workflows/claude-review.yml, `name: PR Review`.
232+
REVIEW_WORKFLOW_NAME = "PR Review"
233+
234+
235+
def _pipeline_of_review(review, repository, api):
236+
"""The successful Pipeline run of the head a completed review ran on.
237+
238+
The review and the Pipeline finish in either order (ADR-1127). When the
239+
review ends last, its completion wakes the resolver, which then needs the
240+
Pipeline run of the same head: the newest one that succeeded. Without one
241+
the merge is held, and the Pipeline's own completion will wake the resolver.
242+
"""
243+
require(
244+
review.get("path") == ".github/workflows/claude-review.yml"
245+
and review.get("event") == "pull_request"
246+
and review.get("status") == "completed"
247+
and review.get("conclusion") == "success",
248+
"source review did not complete successfully",
249+
)
250+
require(
251+
review.get("head_repository", {}).get("full_name") == repository,
252+
"source head repository differs",
253+
)
254+
head = full_sha(review.get("head_sha"))
255+
path = f"/repos/{repository}/actions/workflows/pipeline.yml/runs"
256+
runs = [
257+
run
258+
for run in api.records(
259+
f"{path}?head_sha={head}&event=pull_request&status=success",
260+
"workflow_runs",
261+
)
262+
if run.get("head_sha") == head and type(run.get("id")) is int
263+
]
264+
require(runs, "merge held: Pipeline has not succeeded on this head")
265+
return max(runs, key=lambda run: run["id"])
266+
267+
231268
def _source_run(event, repository, api):
232269
require(
233270
re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository),
@@ -238,8 +275,12 @@ jobs:
238275
"event repository differs",
239276
)
240277
source = event.get("workflow_run")
241-
_validate_run(source, repository)
278+
require(isinstance(source, dict), "missing workflow_run")
242279
prefix = f"/repos/{repository}"
280+
woken_by_review = source.get("name") == REVIEW_WORKFLOW_NAME
281+
if woken_by_review:
282+
source = _pipeline_of_review(source, repository, api)
283+
_validate_run(source, repository)
243284
run = api.request("GET", f"{prefix}/actions/runs/{source['id']}")
244285
_validate_run(run, repository)
245286
require(
@@ -250,6 +291,7 @@ jobs:
250291
run.get("run_attempt") == source.get("run_attempt"),
251292
"source run has a newer attempt",
252293
)
294+
run["woken_by_review"] = woken_by_review
253295
jobs = _effective_jobs(
254296
api.records(f"{prefix}/actions/runs/{run['id']}/jobs?filter=all", "jobs"), run
255297
)
@@ -472,6 +514,14 @@ jobs:
472514
"pr_number": str(number),
473515
"reason": "An exact-SHA main push Pipeline already exists",
474516
}
517+
if already_merged and run.get("woken_by_review"):
518+
# The Pipeline's completion merged this PR and tests the merge commit.
519+
return {
520+
"tested_sha": sha,
521+
"run_tests": "false",
522+
"pr_number": str(number),
523+
"reason": "Already merged when the review completed",
524+
}
475525
return {
476526
"tested_sha": sha,
477527
"run_tests": "true",

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,9 @@ adheres to [Semantic Versioning](https://semver.org/).
123123

124124
### Changed
125125

126+
- The resolver is also woken by the end of the Claude review, not only by the end
127+
of the Pipeline, so a pull request merges whichever finishes first (ADR-1127,
128+
amends ADR-1121).
126129
- A Dependabot minor or patch update that touches only `uv.lock` or `pyproject.toml`
127130
merges on green required checks without a Claude verdict (ADR-1126, amends
128131
ADR-1121). Major updates, workflow or Dockerfile updates and every other pull
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<!-- Generated by Cortex wiki_reindex from wiki/adr/cortex/1127-the-review-s-completion-wakes-the-resolver-as-the-pipeline-s-does.md; ADR-1127. Read-only mirror: edit the canonical wiki page. -->
2+
3+
---
4+
created: 2026-11-10T01:40:00Z
5+
kind: adr
6+
number: 1127
7+
status: accepted
8+
tags: [ci, review, merge, resolver, amends-adr-1121]
9+
title: The review's completion wakes the resolver as the Pipeline's does
10+
---
11+
# ADR-1127: The review's completion wakes the resolver as the Pipeline's does
12+
13+
## Status
14+
15+
accepted. Amends ADR-1121 (the Claude review verdict decides the merge).
16+
17+
## Context
18+
19+
`pipeline-after-merge.yml` called the resolver on the completion of `Pipeline` only. The resolver reads the verdict once, without polling (ADR-1121). So the merge depended on an order: the review had to end before the Pipeline. In Cortex the Pipeline lasts about 30 minutes and the review 3 to 4, so the order held. It does not hold in a repository whose Pipeline is shorter than its review, nor when the review is queued behind runners: the Pipeline ends, the resolver finds no verdict and holds the merge, and nothing wakes it when the `Verdict: approve` arrives. The pull request stays open until someone re-runs the Pipeline or merges by hand. Codex reported it on the pull requests that replicate this CI (ai-architect-mcp-codebase #486, ai-architect-mcp-spec #185).
20+
21+
## Decision
22+
23+
1. `pipeline-after-merge.yml` listens to the completion of both `Pipeline` and `PR Review`.
24+
2. Woken by a review, the resolver takes as its source the newest successful `pull_request` run of `pipeline.yml` on the review's head. That run then goes through every check the Pipeline's own completion goes through (run identity, exact job results, pull request identity, verdict or low-risk tier). Without such a run the merge is held: the Pipeline's completion will wake the resolver.
25+
3. A pull request already merged when the review ends is left alone: the wake-up that merged it tests the merge commit.
26+
4. The review run must itself be a completed, successful `pull_request` run of `claude-review.yml` from this repository; a review that was skipped by its budget wakes the resolver too and is held by ADR-1121 as before.
27+
28+
## Consequences
29+
30+
Positive: the merge no longer depends on which workflow finishes first; no polling is added.
31+
32+
Negative: each pull request head wakes the resolver twice. The wake-up that comes first is held and ends in failure (no verdict yet, or no Pipeline yet), which is the expected trace of the order, not a defect.
33+
34+
Tests: `tests_py/scripts/test_ci_review_wakes_resolver.py`, `tests_py/scripts/test_ci_pipeline_routes.py` (the caller's event contract).

‎scripts/ci_pipeline_routes.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,10 @@
1414
"push: branches: [main]"
1515
)
1616
ENGINE_EVENTS = "workflow_call: secrets: RELEASE_TAG_SSH_KEY: required: false"
17+
# The review's completion wakes the resolver as the Pipeline's does (ADR-1127).
1718
CALLER_EVENTS = (
18-
"workflow_run: workflows: [Pipeline] types: [completed] branches-ignore: [main]"
19+
"workflow_run: workflows: [Pipeline, PR Review] types: [completed] "
20+
"branches-ignore: [main]"
1921
)
2022
CALLER_CONDITION = (
2123
"github.event.workflow_run.event == 'pull_request' "

‎tests_py/scripts/test_ci_pipeline_routes.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ def test_caller_cannot_inherit_all_secrets_or_gain_review_permissions(self):
6969
("github.event.workflow_run.conclusion == 'success'", "true"),
7070
("github.event.workflow_run.event == 'pull_request'", "true"),
7171
("branches-ignore: [main]", "branches-ignore: [other]"),
72-
("workflows: [Pipeline]", "workflows: [Other]"),
72+
("workflows: [Pipeline, PR Review]", "workflows: [Other]"),
7373
):
7474
with self.subTest(before=before):
7575
changed = self.caller.replace(before, after)
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
"""The review's completion wakes the resolver too, so the merge does not depend on
2+
which of the review and the Pipeline finishes first (ADR-1127)."""
3+
4+
from pathlib import Path
5+
import textwrap
6+
import unittest
7+
8+
ROOT = Path(__file__).resolve().parents[2]
9+
WORKFLOWS = ROOT / ".github/workflows"
10+
REPO = "cdeust/Cortex"
11+
HEAD = "a" * 40
12+
13+
14+
def resolver():
15+
text = (WORKFLOWS / "pipeline-post-merge.yml").read_text()
16+
source = text.split(" python3 - <<'PY'\n", 1)[1].split(
17+
"\n PY", 1
18+
)[0]
19+
namespace = {"__name__": "resolver_test"}
20+
exec(compile(textwrap.dedent(source), "trusted_resolver", "exec"), namespace)
21+
return namespace
22+
23+
24+
def review(**changes):
25+
run = {
26+
"name": "PR Review",
27+
"path": ".github/workflows/claude-review.yml",
28+
"event": "pull_request",
29+
"status": "completed",
30+
"conclusion": "success",
31+
"head_repository": {"full_name": REPO},
32+
"head_sha": HEAD,
33+
}
34+
return {**run, **changes}
35+
36+
37+
class FakeApi:
38+
def __init__(self, pipelines):
39+
self.pipelines, self.paths = pipelines, []
40+
41+
def records(self, path, key=None):
42+
self.paths.append(path)
43+
return self.pipelines
44+
45+
46+
class ReviewWakesResolverTests(unittest.TestCase):
47+
def pipeline_of(self, source, pipelines):
48+
api = FakeApi(pipelines)
49+
return resolver()["_pipeline_of_review"](source, REPO, api), api
50+
51+
def held(self, source, pipelines, message):
52+
ns = resolver()
53+
with self.assertRaises(ns["PostMergeError"]) as caught:
54+
ns["_pipeline_of_review"](source, REPO, FakeApi(pipelines))
55+
self.assertIn(message, str(caught.exception))
56+
57+
def test_the_newest_successful_pipeline_of_the_head_is_the_source(self):
58+
runs = [{"id": 5, "head_sha": HEAD}, {"id": 9, "head_sha": HEAD}]
59+
found, api = self.pipeline_of(review(), runs)
60+
self.assertEqual(found["id"], 9)
61+
self.assertEqual(
62+
api.paths,
63+
[
64+
f"/repos/{REPO}/actions/workflows/pipeline.yml/runs"
65+
f"?head_sha={HEAD}&event=pull_request&status=success"
66+
],
67+
)
68+
69+
def test_a_pipeline_of_another_head_does_not_count(self):
70+
self.held(review(), [{"id": 9, "head_sha": "b" * 40}], "has not succeeded")
71+
72+
def test_no_successful_pipeline_holds_the_merge(self):
73+
self.held(review(), [], "Pipeline has not succeeded on this head")
74+
75+
def test_a_review_that_failed_or_ran_elsewhere_is_refused(self):
76+
for change in (
77+
{"conclusion": "failure"},
78+
{"status": "in_progress"},
79+
{"event": "pull_request_target"},
80+
{"path": ".github/workflows/other.yml"},
81+
):
82+
self.held(review(**change), [], "did not complete successfully")
83+
fork = review(head_repository={"full_name": "someone/Cortex"})
84+
self.held(fork, [], "head repository differs")
85+
86+
def test_a_pr_merged_before_the_review_ended_is_not_tested_twice(self):
87+
text = (WORKFLOWS / "pipeline-post-merge.yml").read_text()
88+
body = text.split("def resolve(event", 1)[1].split("def main", 1)[0]
89+
held = body.split('run.get("woken_by_review")', 1)[1].split("return {", 2)[1]
90+
self.assertIn('"run_tests": "false"', held)
91+
self.assertLess(
92+
body.index('run.get("woken_by_review")'),
93+
body.index('"run_tests": "true"'),
94+
)
95+
96+
def test_both_workflows_wake_the_resolver(self):
97+
caller = (WORKFLOWS / "pipeline-after-merge.yml").read_text()
98+
self.assertIn("workflows: [Pipeline, PR Review]", caller)
99+
review_name = (WORKFLOWS / "claude-review.yml").read_text().splitlines()[0]
100+
self.assertEqual(review_name, "name: PR Review")
101+
102+
103+
if __name__ == "__main__":
104+
unittest.main()
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
created: 2026-11-10T01:40:00Z
3+
kind: adr
4+
number: 1127
5+
status: accepted
6+
tags: [ci, review, merge, resolver, amends-adr-1121]
7+
title: The review's completion wakes the resolver as the Pipeline's does
8+
---
9+
# ADR-1127: The review's completion wakes the resolver as the Pipeline's does
10+
11+
## Status
12+
13+
accepted. Amends ADR-1121 (the Claude review verdict decides the merge).
14+
15+
## Context
16+
17+
`pipeline-after-merge.yml` called the resolver on the completion of `Pipeline` only. The resolver reads the verdict once, without polling (ADR-1121). So the merge depended on an order: the review had to end before the Pipeline. In Cortex the Pipeline lasts about 30 minutes and the review 3 to 4, so the order held. It does not hold in a repository whose Pipeline is shorter than its review, nor when the review is queued behind runners: the Pipeline ends, the resolver finds no verdict and holds the merge, and nothing wakes it when the `Verdict: approve` arrives. The pull request stays open until someone re-runs the Pipeline or merges by hand. Codex reported it on the pull requests that replicate this CI (ai-architect-mcp-codebase #486, ai-architect-mcp-spec #185).
18+
19+
## Decision
20+
21+
1. `pipeline-after-merge.yml` listens to the completion of both `Pipeline` and `PR Review`.
22+
2. Woken by a review, the resolver takes as its source the newest successful `pull_request` run of `pipeline.yml` on the review's head. That run then goes through every check the Pipeline's own completion goes through (run identity, exact job results, pull request identity, verdict or low-risk tier). Without such a run the merge is held: the Pipeline's completion will wake the resolver.
23+
3. A pull request already merged when the review ends is left alone: the wake-up that merged it tests the merge commit.
24+
4. The review run must itself be a completed, successful `pull_request` run of `claude-review.yml` from this repository; a review that was skipped by its budget wakes the resolver too and is held by ADR-1121 as before.
25+
26+
## Consequences
27+
28+
Positive: the merge no longer depends on which workflow finishes first; no polling is added.
29+
30+
Negative: each pull request head wakes the resolver twice. The wake-up that comes first is held and ends in failure (no verdict yet, or no Pipeline yet), which is the expected trace of the order, not a defect.
31+
32+
Tests: `tests_py/scripts/test_ci_review_wakes_resolver.py`, `tests_py/scripts/test_ci_pipeline_routes.py` (the caller's event contract).

‎wiki/manifest.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3675,6 +3675,10 @@
36753675
"ADR-1126": {
36763676
"mirror": "ADR-1126-a-dependabot-minor-or-patch-update-of-the-dependency-files-merges-without-a-review.md",
36773677
"path": "adr/cortex/1126-a-dependabot-minor-or-patch-update-of-the-dependency-files-merges-without-a-review.md"
3678+
},
3679+
"ADR-1127": {
3680+
"mirror": "ADR-1127-the-review-s-completion-wakes-the-resolver-as-the-pipeline-s-does.md",
3681+
"path": "adr/cortex/1127-the-review-s-completion-wakes-the-resolver-as-the-pipeline-s-does.md"
36783682
}
36793683
},
36803684
"project": "cortex",

0 commit comments

Comments
 (0)