Skip to content

Commit ccfa72b

Browse files
shenxianpengclaude
andcommitted
feat(output): expose the rendered report and fix the fork-PR comment pattern
The two-workflow pattern in docs/fork-pr-comments.md and examples/ told Workflow A to upload `result.txt`, a file the action has never written, and did so without `if: always()`, so on the failing runs that need a comment the upload step never ran at all. Workflow B then re-rendered a comment under a title the action no longer recognises as its own, and read the PR number from `workflow_run.pull_requests[0]`, which is empty for fork PRs. Add a `report` output beside `result`: the Markdown report byte for byte, marker to footer, written to GITHUB_OUTPUT in the same heredoc form. A workflow_run job can post it verbatim, so the fork comment is identical to one the action posts itself and a later `pr-comments: true` run adopts it instead of adding a second one. Rewrite the doc and both examples around it: Workflow A saves report.md, result.json and pr-number under `if: always()`; Workflow B downloads by run id and updates the comment carrying `<!-- commit-check-action -->`. Document the output in the README and fix the diagram labels. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018xYa7m3qup5wyN5MaXFgf6
1 parent 046b66d commit ccfa72b

7 files changed

Lines changed: 188 additions & 54 deletions

File tree

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,28 @@ check outcomes (`rule_id`, `check`, `status`, `value`, `error`, `suggest`,
258258
`fix`, `docs_url`) exactly as produced by `commit-check --format json`, so
259259
downstream jobs can build their own reports or gate on individual rules.
260260

261+
### `report`
262+
263+
The rendered Markdown report — byte for byte the text the
264+
[job summary](#github-action-job-summary) and the
265+
[PR comment](#github-pull-request-comments) show, opening with the
266+
`<!-- commit-check-action -->` marker. It exists for workflows that have to post
267+
the comment themselves: a `pull_request` run on a fork has a read-only token, so
268+
it saves the report as an artifact and a `workflow_run` job posts it verbatim —
269+
see [Fork PR Comments](docs/fork-pr-comments.md). Because the text is the
270+
action's own, that comment is later found and edited in place like any other.
271+
272+
```yaml
273+
- name: Save the report
274+
if: always() && steps.commit-check.outputs.report != ''
275+
env:
276+
REPORT: ${{ steps.commit-check.outputs.report }}
277+
run: printf '%s\n' "$REPORT" > report.md
278+
```
279+
280+
Treat `report` as text to display, not data to parse; `result` is the contract
281+
for that.
282+
261283
## GitHub Action Job Summary
262284

263285
By default, commit-check-action results are shown on the job summary page of the

‎action.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,9 @@ outputs:
4444
# mapping (and the step id it refers to) the output is always the empty
4545
# string, and fromJSON('') fails the calling workflow.
4646
value: ${{ steps.commit-check.outputs.result }}
47+
report:
48+
description: The rendered Markdown report, byte for byte what the job summary and PR comment show. Save it as an artifact from a pull_request run and post it verbatim from a workflow_run job to comment on fork pull requests (see docs/fork-pr-comments.md).
49+
value: ${{ steps.commit-check.outputs.report }}
4750

4851
runs:
4952
using: "composite"

‎docs/fork-pr-comments.md‎

Lines changed: 46 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,16 @@ event with **no security risks**.
2727
2828
**How it works:**
2929

30+
Workflow A runs the checks with `pr-comments: false` and saves the action's
31+
[`report`](../README.md#report) output — the rendered Markdown the job summary shows — plus
32+
the [`result`](../README.md#result) JSON and the PR number, as an artifact. Workflow B,
33+
triggered by `workflow_run` in the base repository, downloads the artifact and posts (or
34+
updates) one comment carrying the `<!-- commit-check-action -->` marker, using `report.md`
35+
verbatim. The fork comment is therefore the same comment the action posts on a non-fork
36+
PR, and a later run with `pr-comments: true` finds and edits it instead of adding a
37+
second one. The artifact contains only `report.md`, `result.json` and `pr-number` — no
38+
code or secrets.
39+
3040
```
3141
pull_request workflow_run
3242
│ │
@@ -36,7 +46,7 @@ event with **no security risks**.
3646
│ (checks) │────►│ (comment writer) │
3747
│ │ │ │
3848
│ Token: READ │ │ Token: WRITE │
39-
│ Saves result │ │ Reads artifact │
49+
│ Saves report │ │ Downloads it │
4050
│ as artifact │ │ Posts PR comment │
4151
└──────────────┘ └──────────────────┘
4252
```
@@ -55,20 +65,40 @@ on:
5565
jobs:
5666
check:
5767
runs-on: ubuntu-latest
68+
permissions:
69+
contents: read
5870
steps:
5971
- uses: actions/checkout@v7
6072
with:
6173
fetch-depth: 0
6274
- uses: commit-check/commit-check-action@v2
75+
id: commit-check
6376
with:
6477
message: true
6578
branch: true
66-
pr-comments: false # comments handled by Workflow B
79+
pr-comments: false # comments handled by Workflow B
6780
job-summary: true
81+
82+
# The action exits 1 on a failure, so both steps below need `always()`
83+
# or the artifact is missing on exactly the runs that need a comment.
84+
# The outputs are written before the action exits, so they are present
85+
# on failing runs too.
86+
- name: Save the report for Workflow B
87+
if: always() && steps.commit-check.outputs.report != ''
88+
env:
89+
REPORT: ${{ steps.commit-check.outputs.report }}
90+
RESULT: ${{ steps.commit-check.outputs.result }}
91+
PR_NUMBER: ${{ github.event.number }}
92+
run: |
93+
mkdir -p commit-check-result
94+
printf '%s\n' "$REPORT" > commit-check-result/report.md
95+
printf '%s\n' "$RESULT" > commit-check-result/result.json
96+
printf '%s\n' "$PR_NUMBER" > commit-check-result/pr-number
6897
- uses: actions/upload-artifact@v4
98+
if: always() && steps.commit-check.outputs.report != ''
6999
with:
70-
name: commit-check-result-${{ github.event.number }}
71-
path: result.txt # saved for Workflow B
100+
name: commit-check-result
101+
path: commit-check-result/
72102
```
73103
74104
> 📄 Full file: [`examples/commit-check-workflow-a.yml`](../examples/commit-check-workflow-a.yml)
@@ -90,25 +120,26 @@ jobs:
90120
runs-on: ubuntu-latest
91121
permissions:
92122
pull-requests: write
93-
actions: read # needed to download artifacts
123+
actions: read # needed to download another run's artifact
94124
steps:
125+
# Download by run id: the PR number travels inside the artifact because
126+
# github.event.workflow_run.pull_requests is empty for fork PRs.
95127
- uses: actions/download-artifact@v4
96128
with:
97-
name: commit-check-result-${{ github.event.workflow_run.pull_requests[0].number }}
129+
name: commit-check-result
98130
run-id: ${{ github.event.workflow_run.id }}
99131
github-token: ${{ github.token }}
100-
- name: Read result and post PR comment
132+
- name: Post or update the PR comment
101133
uses: actions/github-script@v7
102134
with:
103135
script: |
104-
// See examples/commit-check-workflow-b.yml for full script
136+
// See examples/commit-check-workflow-b.yml for the full script
105137
const fs = require('fs');
106-
const prNumber = ${{ github.event.workflow_run.pull_requests[0].number }};
107-
const resultText = fs.readFileSync('result.txt', 'utf8').trim();
108-
const body = resultText
109-
? '# Commit-Check ❌\n```\n' + resultText + '\n```'
110-
: '# Commit-Check ✔️';
111-
// Creates or updates the matching PR comment
138+
const prNumber = Number(fs.readFileSync('pr-number', 'utf8').trim());
139+
const body = fs.readFileSync('report.md', 'utf8'); // posted verbatim
140+
const MARKER = '<!-- commit-check-action -->';
141+
// Finds the comment that starts with MARKER and updates it,
142+
// or creates one when there is none yet
112143
```
113144

114145
> 📄 Full file: [`examples/commit-check-workflow-b.yml`](../examples/commit-check-workflow-b.yml)
@@ -119,7 +150,7 @@ jobs:
119150
permissions (you explicitly grant `pull-requests: write`)
120151
- Workflow B **does not checkout the PR code**, so untrusted fork code never runs
121152
with elevated permissions
122-
- The artifact only contains `result.txt` — no code or secrets
153+
- The artifact only contains `report.md`, `result.json` and `pr-number` — no code or secrets
123154

124155
---
125156

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
# Workflow A: Run commit checks on pull_request events.
22
#
3-
# This workflow is triggered by pull_request and runs commit checks.
4-
# It uploads the result as an artifact so Workflow B (commit-check-comment.yml)
5-
# can read it and post a PR comment with full write permissions.
3+
# This workflow is triggered by pull_request and runs the checks. On a pull
4+
# request from a fork its GITHUB_TOKEN is read-only, so it cannot comment;
5+
# instead it saves the action's `report` and `result` outputs as an artifact
6+
# for Workflow B (commit-check-comment.yml), which runs with write permissions
7+
# in the base repository and posts the report as the PR comment.
68
#
7-
# See https://github.com/commit-check/commit-check-action#fork-pr-comments
9+
# See https://github.com/commit-check/commit-check-action/blob/main/docs/fork-pr-comments.md
810

911
name: Commit Check
1012

@@ -15,19 +17,38 @@ on:
1517
jobs:
1618
check:
1719
runs-on: ubuntu-latest
20+
permissions:
21+
contents: read
1822
steps:
1923
- uses: actions/checkout@v7
2024
with:
2125
fetch-depth: 0
2226
- uses: commit-check/commit-check-action@v2
27+
id: commit-check
2328
with:
2429
message: true
2530
branch: true
2631
pr-comments: false # comments handled by Workflow B
2732
job-summary: true
2833

29-
# Save results so Workflow B can post a PR comment
34+
# The action exits 1 on a failure, so both steps below need `always()`
35+
# or the artifact is missing on exactly the runs that need a comment.
36+
# The outputs are written before the action exits, so they are present
37+
# on failing runs too; the second condition only skips the upload when
38+
# the action itself could not run.
39+
- name: Save the report for Workflow B
40+
if: always() && steps.commit-check.outputs.report != ''
41+
env:
42+
REPORT: ${{ steps.commit-check.outputs.report }}
43+
RESULT: ${{ steps.commit-check.outputs.result }}
44+
PR_NUMBER: ${{ github.event.number }}
45+
run: |
46+
mkdir -p commit-check-result
47+
printf '%s\n' "$REPORT" > commit-check-result/report.md
48+
printf '%s\n' "$RESULT" > commit-check-result/result.json
49+
printf '%s\n' "$PR_NUMBER" > commit-check-result/pr-number
3050
- uses: actions/upload-artifact@v4
51+
if: always() && steps.commit-check.outputs.report != ''
3152
with:
32-
name: commit-check-result-${{ github.event.number }}
33-
path: result.txt
53+
name: commit-check-result
54+
path: commit-check-result/

‎examples/commit-check-workflow-b.yml‎

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
1-
# Workflow B: Post PR comment after commit checks complete.
1+
# Workflow B: Post the PR comment after Workflow A completes.
22
#
3-
# This workflow is triggered by the workflow_run event from Workflow A.
4-
# It runs in the base repository's context with full write permissions,
5-
# making it safe for fork PRs (no checkout of fork code).
3+
# This workflow is triggered by the workflow_run event from Workflow A. It
4+
# runs in the base repository's context with the permissions granted below,
5+
# which makes it safe for fork PRs: it never checks out the fork's code, it
6+
# only downloads the artifact Workflow A saved and posts report.md verbatim.
67
#
78
# Prerequisites:
8-
# - Workflow A (commit-check.yml) must exist and upload an artifact named
9-
# commit-check-result-<PR-number> containing result.txt
9+
# - Workflow A (commit-check.yml) must exist, be named "Commit Check", and
10+
# upload an artifact named commit-check-result containing report.md and
11+
# pr-number (see commit-check-workflow-a.yml).
1012
#
11-
# See https://github.com/commit-check/commit-check-action#fork-pr-comments
13+
# See https://github.com/commit-check/commit-check-action/blob/main/docs/fork-pr-comments.md
1214

1315
name: Commit Check Comment
1416

@@ -22,36 +24,40 @@ jobs:
2224
runs-on: ubuntu-latest
2325
permissions:
2426
pull-requests: write
25-
actions: read # needed to download artifacts
27+
actions: read # needed to download another run's artifact
2628
steps:
29+
# Download by run id: the PR number travels inside the artifact because
30+
# github.event.workflow_run.pull_requests is empty for fork PRs.
2731
- uses: actions/download-artifact@v4
2832
with:
29-
name: commit-check-result-${{ github.event.workflow_run.pull_requests[0].number }}
33+
name: commit-check-result
3034
run-id: ${{ github.event.workflow_run.id }}
3135
github-token: ${{ github.token }}
3236

33-
- name: Read result and post PR comment
37+
- name: Post or update the PR comment
3438
uses: actions/github-script@v7
3539
with:
3640
script: |
3741
const fs = require('fs');
38-
const prNumber = ${{ github.event.workflow_run.pull_requests[0].number }};
39-
const resultText = fs.readFileSync('result.txt', 'utf8').trim();
42+
const prNumber = Number(fs.readFileSync('pr-number', 'utf8').trim());
43+
if (!Number.isInteger(prNumber) || prNumber <= 0) {
44+
core.setFailed(`Artifact carries no pull request number (got ${JSON.stringify(prNumber)})`);
45+
return;
46+
}
4047
41-
const successTitle = '# Commit-Check ✔️';
42-
const failureTitle = '# Commit-Check ❌';
43-
const body = resultText
44-
? `${failureTitle}\n\`\`\`\n${resultText}\n\`\`\``
45-
: successTitle;
48+
// report.md is the action's `report` output: the same Markdown the
49+
// action posts itself, opening with the marker it uses to find its
50+
// own comment. Posting it unchanged means a later run with
51+
// `pr-comments: true` edits this comment instead of adding one.
52+
const body = fs.readFileSync('report.md', 'utf8');
53+
const MARKER = '<!-- commit-check-action -->';
4654
47-
const { data: comments } = await github.rest.issues.listComments({
55+
const comments = await github.paginate(github.rest.issues.listComments, {
4856
...context.repo,
4957
issue_number: prNumber,
58+
per_page: 100,
5059
});
51-
52-
const existing = comments.find(c =>
53-
c.body.startsWith(successTitle) || c.body.startsWith(failureTitle)
54-
);
60+
const existing = comments.find(c => (c.body ?? '').startsWith(MARKER));
5561
5662
if (existing) {
5763
await github.rest.issues.updateComment({

‎main.py‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@
88
* **step log** — grouped sections, then one ``::error`` annotation per finding
99
* **job summary** — a Markdown policy report table
1010
* **PR comment** — a compact Markdown summary (idempotently updated)
11+
12+
and exposes two action outputs: ``result`` (the check data as JSON) and
13+
``report`` (the rendered Markdown, for workflows that post the comment
14+
themselves).
1115
"""
1216

1317
import json
@@ -1195,6 +1199,10 @@ def _scope_value(scope: ScopeResult, max_len: int = 60) -> str:
11951199
# one value the reader has to act on and the cap can hide the reason.
11961200
# - The step log renders the same tree (_render_scopes); it adds the docs URL,
11971201
# which the Markdown report already carries on the rule ID in the table.
1202+
# - The whole report, marker to footer, is also written verbatim to the
1203+
# `report` action output beside the JSON `result`, so a workflow_run job can
1204+
# post it for a fork pull request and produce the same comment this action
1205+
# would have posted itself.
11981206
# ---------------------------------------------------------------------------
11991207

12001208

@@ -1295,9 +1303,21 @@ def add_job_summary(results: list[ScopeResult]) -> int:
12951303

12961304

12971305
def set_result_output(results: list[ScopeResult]) -> None:
1298-
"""Expose the structured results as the ``result`` action output.
1299-
1300-
Uses the heredoc form of ``GITHUB_OUTPUT`` so multi-line JSON survives.
1306+
"""Expose the results as the ``result`` and ``report`` action outputs.
1307+
1308+
``result`` is the structured JSON downstream steps gate on. ``report`` is
1309+
the rendered Markdown — the very text the job summary and the PR comment
1310+
show — for the one caller that cannot post it itself: a ``pull_request``
1311+
run on a fork has a read-only token, so it hands the report to a
1312+
``workflow_run`` job that posts it verbatim (docs/fork-pr-comments.md).
1313+
Shipping the text rather than making that job re-render the JSON keeps
1314+
the fork comment identical to every other one, marker and footer
1315+
included, so a later run with ``pr-comments: true`` adopts it.
1316+
1317+
Uses the heredoc form of ``GITHUB_OUTPUT`` so multi-line values survive.
1318+
Neither value can contain a bare ``EOF`` line: JSON lines are quoted or
1319+
punctuation, and every line of user text in the report is indented or
1320+
sits inside a table row.
13011321
"""
13021322
output_path = os.getenv("GITHUB_OUTPUT")
13031323
if not output_path:
@@ -1318,6 +1338,9 @@ def set_result_output(results: list[ScopeResult]) -> None:
13181338
f.write("result<<EOF\n")
13191339
f.write(json.dumps(payload, indent=2))
13201340
f.write("\nEOF\n")
1341+
f.write("report<<EOF\n")
1342+
f.write(render_report(results))
1343+
f.write("\nEOF\n")
13211344

13221345

13231346
def is_fork_pr() -> bool:

0 commit comments

Comments
 (0)