ci: pin the doc bot to the merge commit and always report the outcome - #25762
Conversation
The bot runs when a pull request is merged, which is the one moment its head branch no longer exists: GitHub deletes it on merge. gh-aw emits a "Checkout PR branch" step for every pull request trigger, so every run failed it and wrote an expected-failure warning into its summary. `pull_request_target` is the trigger gh-aw suppresses that step for, and pinning the checkout to the merge commit makes the tree the agent reads right by construction rather than by coincidence. The standing comment is mandatory now, including for the runs that write no documentation, so whoever merged the pull request does not have to open a run log to find out how the run ended.
Type of change
How to testThe trigger only fires on a merge into
What changed in detail
It is a shape match, not an analysis of the ref. The checkout is pinned to The compiled diff is only these removals and one addition:
Evidence from the runsThe run for #25710 ( and, a few seconds earlier, the workspace landing on the right commit
For the fork half: #25606 was merged from a fork on 10 September. Its |
The trigger swap drops a step, and the checkout ref is pinned instead of assumedflowchart LR
subgraph Before
direction TB
B1["pull_request (closed, merged)"] -->|"checks out github.sha (default)"| B2["actions/checkout"]
B1 -->|"fetches head branch by name"| B3["Checkout PR branch (checkout-pr): fails, branch deleted on merge"]
B1 -->|"runs Phase 0-5"| B4["Phase 6: comment, or noop if nothing to report"]
end
subgraph After
direction TB
A1["pull_request_target (closed, merged)"] -->|"checks out merge_commit_sha (new)"| A2["actions/checkout"]:::changed
A1 -->|"runs Phase 0-5"| A3["Phase 6: always comments, one of three shapes (new)"]:::changed
end
Before ~~~ After
classDef changed stroke:#c9a227,stroke-width:3px
Switching the trigger from Diagram Bot draws the mechanism this pull request touches; it does not review the change. Verify it against the diff.
|
…r-docs-bot Conflicts in the doc bot's prompt and its compiled lock file, both from #25760 landing on main in the meantime. Phase 6 keeps that pull request's `<REFERENCE>` paragraph and loses its "do not comment when you recorded a `noop`" line, which this branch's mandatory comment replaces. The lock file was recompiled with `gh aw compile` rather than merged by hand. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#25797 raised the doc bot's bar on main and, in doing so, added `noop` instructions to Phase 0, Phase 2, Phase 3 and a new self-check — the outcome this branch replaces with a mandatory Phase 6 comment. Its substance is kept whole; each `noop` it records is routed to that comment instead, and Phase 6 gains a fourth shape for the open pull request under the old `[docs] ` prefix that #25797 introduced. The lock file was recompiled with `gh aw compile` rather than merged by hand. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The same fix landed on main in #25762: `create-pull-request` now carries `assignees`, the `assign-to-user` output is gone, and Phase 5a tells the agent the assignment is done for it. Both conflicting files are resolved to main's version, which says all of that and keeps the wording of the surrounding rewrite that came with it. Nothing is left on this branch that main does not already have.
2 participants
DX/docs · doc-bot workflow · everyone merging a pull request to
mainBackground — the gh-aw pull request checkout. A workflow compiled by
gh-aw from a pull request trigger always gets a "Checkout PR branch" step
that fetches the head branch by name. gh-aw suppresses that step for
pull_request_target, a change its ADR-46771 made for this situation.The bot runs when a pull request is merged, the one moment its head branch
no longer exists, because GitHub deletes it on merge. Every run therefore
failed the branch checkout and wrote an expected-failure warning into its
summary. The bot also said nothing when it found no documentation was
needed, so the only way to learn how a run ended was to open the run log.
Risks:
pull_requestrun from a fork gets no secrets, so those merges went undocumented.
The same-repository guard the compiler injected for
pull_requestisgone with the trigger, as is a stacked-pull-request guard.
request now, the runs that write no documentation included.
pull_request_targetruns with secrets in reach. Nothing untrustedruns: the workspace is pinned to a commit that is already on
main, andthe workflow never builds or runs the project. The compiler warns about
the combination anyway, because it matches on the shape, not on the ref.
Context. The failing step broke nothing, because
github.shahappensto be the merge commit for a merged pull request. It did hide an
inconsistency: when a head branch survived the merge, the step succeeded
and moved the workspace onto the pull request head instead.
pull_request_target, which drops the "CheckoutPR branch" step and its
checkout_pr_successoutputdocumentation written, nothing to document, or documentation rejected by
an earlier review
noopsafe-output and told the agent not to reach for thebuilt-in one, because the standing comment is the record of a run now