Skip to content

Commit 0db5e82

Browse files
shenxianpengclaude
andcommitted
refactor: drop the report output and the two-workflow fork pattern for the App
A fork pull request only loses the comment: the check status, the annotations on the Files changed tab, the job summary and the result output all work, and pr-comments on a fork is a no-op rather than an error. The two-workflow pattern spent two files, an artifact round trip, actions: read and a smuggled PR number to move information the contributor could already see into a comment, and the report output existed only to feed it. The Commit Check GitHub App receives the pull_request webhook on the base repository and acts with its own token, so fork PRs are ordinary PRs to it: one check run per commit, no workflow file, free on public repositories, which is where fork PRs happen. docs/fork-pr-comments.md now says what a fork contributor actually sees, points at the App, and keeps pull_request_target with its security warning for anyone who cannot install one. The file name stays so links from released versions still resolve. The random heredoc delimiter stays: it protects the result output, whose JSON quotes commit subjects and error text as they are. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018xYa7m3qup5wyN5MaXFgf6
1 parent d216058 commit 0db5e82

7 files changed

Lines changed: 101 additions & 395 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ A GitHub Action for checking commit message formatting, branch naming, committer
2929
* [GitHub Action Job Summary](#github-action-job-summary)
3030
* [GitHub Pull Request Comments](#github-pull-request-comments)
3131
* [Advanced Configuration](#advanced-configuration)
32-
* [Fork PR Comments](docs/fork-pr-comments.md)
32+
* [Fork Pull Requests](docs/fork-pr-comments.md)
3333
* [Badging Your Repository](#badging-your-repository)
3434
* [Versioning](#versioning)
3535

@@ -106,8 +106,8 @@ can see.
106106
| | GitHub Action (this repo) | [pre-commit hook](https://github.com/commit-check/commit-check#use-with-pre-commit) | [Commit Check GitHub App](https://github.com/marketplace/commit-check) |
107107
|---|---|---|---|
108108
| **Where it runs** | In your workflow, on the runner, after the push | On the contributor's machine, at `git commit` / `git push` | Hosted by commit-check; installed on the repository, no workflow file |
109-
| **What it checks** | Every PR commit's message, plus the PR title, branch and author checks you enable; renders a job summary, annotations, a PR comment and the `result` / `report` outputs | Message (`commit-msg` stage), branch, author; tag, force-push and files (`pre-push`) — one commit at a time, before it exists | Every commit of a push or pull request: message, branch, author (the PR title only in squash mode); reported as one **Commit Check** check run per commit |
110-
| **When to pick it** | You want enforcement in CI that a contributor cannot skip, per-rule outputs for later steps, or you run on GitHub Enterprise Server / need `CCHK_*` overrides | You want the fastest feedback and to stop bad commits before they are pushed; pair it with the Action, since hooks are opt-in | You want zero YAML and no Actions minutes; fork PRs get a check run without the [two-workflow pattern](docs/fork-pr-comments.md) (no PR comment, though) |
109+
| **What it checks** | Every PR commit's message, plus the PR title, branch and author checks you enable; renders a job summary, annotations, a PR comment and the `result` output | Message (`commit-msg` stage), branch, author; tag, force-push and files (`pre-push`) — one commit at a time, before it exists | Every commit of a push or pull request: message, branch, author (the PR title only in squash mode); reported as one **Commit Check** check run per commit |
110+
| **When to pick it** | You want enforcement in CI that a contributor cannot skip, per-rule outputs for later steps, or you run on GitHub Enterprise Server / need `CCHK_*` overrides | You want the fastest feedback and to stop bad commits before they are pushed; pair it with the Action, since hooks are opt-in | You want zero YAML and no Actions minutes, or feedback on [fork pull requests](docs/fork-pr-comments.md) without the Action's read-only-token limits |
111111

112112
Most teams pair the pre-commit hook (fast, local) with the Action (enforced):
113113
the hook catches a bad message before it is pushed, and the Action is why CI
@@ -180,9 +180,10 @@ fails when a contributor did not install the hook.
180180
> [!NOTE]
181181
> `pr-comments` is disabled by default.
182182
>
183-
> PR comments are skipped for pull requests from forked repositories. See
184-
> [docs/fork-pr-comments.md](docs/fork-pr-comments.md) for details on how to enable
185-
> this feature for fork contributions.
183+
> PR comments are skipped for pull requests from forked repositories, whose
184+
> `GITHUB_TOKEN` is read-only. Everything else still works there: the check
185+
> status, the annotations and the job summary. See
186+
> [Fork pull requests](docs/fork-pr-comments.md).
186187
>
187188
> **Dependabot pull requests** are not forks, but GitHub gives their
188189
> `pull_request` runs a read-only `GITHUB_TOKEN` by default. The `permissions`
@@ -314,28 +315,6 @@ check outcomes (`rule_id`, `check`, `status`, `value`, `error`, `suggest`,
314315
`fix`, `docs_url`) exactly as produced by `commit-check --format json`, so
315316
downstream jobs can build their own reports or gate on individual rules.
316317

317-
### `report`
318-
319-
The rendered Markdown report — byte for byte the text the
320-
[job summary](#github-action-job-summary) and the
321-
[PR comment](#github-pull-request-comments) show, opening with the
322-
`<!-- commit-check-action -->` marker. It exists for workflows that have to post
323-
the comment themselves: a `pull_request` run on a fork has a read-only token, so
324-
it saves the report as an artifact and a `workflow_run` job posts it verbatim —
325-
see [Fork PR Comments](docs/fork-pr-comments.md). Because the text is the
326-
action's own, that comment is later found and edited in place like any other.
327-
328-
```yaml
329-
- name: Save the report
330-
if: always() && steps.commit-check.outputs.report != ''
331-
env:
332-
REPORT: ${{ steps.commit-check.outputs.report }}
333-
run: printf '%s' "$REPORT" > report.md
334-
```
335-
336-
Treat `report` as text to display, not data to parse; `result` is the contract
337-
for that.
338-
339318
## GitHub Action Job Summary
340319

341320
By default, commit-check-action results are shown on the job summary page of the
@@ -541,10 +520,13 @@ By default, commit-check-action handles this gracefully:
541520
- A **notice is added to the Job Summary** explaining why and how to fix it
542521
- The commit checks themselves **still run normally**
543522

544-
> **For most projects, this is sufficient** — contributors can see check results in the
545-
> action Job Summary. But if you *must* have PR comments on fork contributions, see
546-
> the **[Fork PR Comments](docs/fork-pr-comments.md)** documentation for
547-
> two recommended approaches with ready-to-use workflow examples.
523+
> **For most projects, this is sufficient** — a fork contributor already gets the red
524+
> check, the per-finding annotations on their diff and the full report in the job
525+
> summary. If you want feedback on the pull request itself, the
526+
> [Commit Check GitHub App](https://github.com/marketplace/commit-check) posts a check
527+
> run per commit with no workflow file (free on public repositories), or you can run
528+
> this action on `pull_request_target`. Both are covered in
529+
> **[Fork pull requests](docs/fork-pr-comments.md)**.
548530

549531
## Badging Your Repository
550532

‎action.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,6 @@ 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 }}
5047

5148
runs:
5249
using: "composite"

‎docs/fork-pr-comments.md‎

Lines changed: 61 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -1,189 +1,77 @@
1-
# Fork PR Comments
1+
# Fork Pull Requests
22

3-
When a pull request is opened from a **forked repository**, the `GITHUB_TOKEN` used by the
4-
`pull_request` event has **read-only** permissions by design (GitHub security policy).
5-
This means `pr-comments: true` cannot write a comment back to the PR.
3+
When a pull request comes from a **forked repository**, the `GITHUB_TOKEN` of the
4+
`pull_request` event is **read-only** by design (GitHub security policy). That single
5+
restriction is worth understanding precisely, because it costs less than it sounds like.
66

7-
By default, commit-check-action handles this gracefully:
7+
## What a fork contributor still sees
88

9-
- PR comment writing is **skipped** with a `::warning::` message in the logs
10-
- A **notice is added to the Job Summary** explaining why and how to fix it
11-
- The commit checks themselves **still run normally**
9+
Everything except the comment. The action does not degrade on a fork PR:
1210

13-
> **For most projects, this is sufficient** — contributors can see check results in the
14-
> action Job Summary. But if you *must* have PR comments on fork contributions, there
15-
> are two recommended approaches.
11+
| Surface | Fork PR | Why |
12+
|---|---|---|
13+
| The check's pass/fail status | ✅ works | the job's own conclusion |
14+
| `::error` annotations on the **Files changed** tab | ✅ works | workflow commands are written by the runner, not the API |
15+
| The **job summary** — the full report table and details | ✅ works | `$GITHUB_STEP_SUMMARY` is a file on the runner |
16+
| The `result` output for later steps | ✅ works | `$GITHUB_OUTPUT` is a file on the runner |
17+
| A **PR comment** | ❌ skipped | writing a comment needs the API, and the token is read-only |
1618

17-
---
18-
19-
## Option 1: Two-workflow pattern (recommended)
20-
21-
This is the **official GitHub-recommended best practice** for writing PR comments from
22-
fork PRs. It uses the [`workflow_run`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run)
23-
event with **no security risks**.
24-
25-
> 📁 Ready-to-use files: [`examples/commit-check-workflow-a.yml`](../examples/commit-check-workflow-a.yml)
26-
> and [`examples/commit-check-workflow-b.yml`](../examples/commit-check-workflow-b.yml)
27-
28-
**How it works:**
29-
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.
19+
So a contributor pushing to a fork already gets the red check, the per-finding annotations
20+
on their diff, and the whole report in the job summary. The action says so in the log:
3921

4022
```
41-
pull_request workflow_run
42-
│ │
43-
▼ ▼
44-
┌──────────────┐ ┌──────────────────┐
45-
│ Workflow A │ │ Workflow B │
46-
│ (checks) │────►│ (comment writer) │
47-
│ │ │ │
48-
│ Token: READ │ │ Token: WRITE │
49-
│ Saves report │ │ Downloads it │
50-
│ as artifact │ │ Posts PR comment │
51-
└──────────────┘ └──────────────────┘
52-
```
53-
54-
### Workflow A
55-
56-
`.github/workflows/commit-check.yml` (triggered by `pull_request`):
57-
58-
```yaml
59-
name: Commit Check
60-
61-
on:
62-
pull_request:
63-
branches: ["main"]
64-
65-
jobs:
66-
check:
67-
runs-on: ubuntu-latest
68-
permissions:
69-
contents: read
70-
steps:
71-
- uses: actions/checkout@v7
72-
with:
73-
fetch-depth: 0
74-
- uses: commit-check/commit-check-action@v2
75-
id: commit-check
76-
with:
77-
message: true
78-
branch: true
79-
pr-comments: false # comments handled by Workflow B
80-
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' "$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
97-
- uses: actions/upload-artifact@v4
98-
if: always() && steps.commit-check.outputs.report != ''
99-
with:
100-
name: commit-check-result
101-
path: commit-check-result/
23+
::warning::Skipping PR comment: pull requests from forked repositories cannot write
24+
comments via the pull_request event (GITHUB_TOKEN is read-only for forks). The findings
25+
are in this job's summary and in the annotations on the Files changed tab.
10226
```
10327

104-
> 📄 Full file: [`examples/commit-check-workflow-a.yml`](../examples/commit-check-workflow-a.yml)
28+
The run is **not** failed by this: `pr-comments: true` on a fork PR is a no-op, not an error.
10529

106-
### Workflow B
30+
## If you want feedback on the pull request itself
10731

108-
`.github/workflows/commit-check-comment.yml` (triggered by `workflow_run`):
32+
### Install the Commit Check GitHub App (recommended)
10933

110-
```yaml
111-
name: Commit Check Comment
34+
The [Commit Check GitHub App](https://github.com/marketplace/commit-check) is not bound by
35+
the `pull_request` token at all: it receives the `pull_request` webhook on the **base**
36+
repository and acts with its own installation token. Fork pull requests are ordinary
37+
pull requests to it.
11238

113-
on:
114-
workflow_run:
115-
workflows: ["Commit Check"] # must match Workflow A's name exactly
116-
types: [completed]
39+
- **No workflow file.** Install it on the repository and it runs.
40+
- **One check run per commit**, with the failing value, the rule and the suggested fix.
41+
A check run is a first-class PR surface: it shows in the merge box and links straight
42+
to the details.
43+
- **Free on public repositories and personal accounts** — which is where fork pull
44+
requests happen. Private organization repositories need the Team plan.
11745

118-
jobs:
119-
comment:
120-
runs-on: ubuntu-latest
121-
permissions:
122-
pull-requests: write
123-
actions: read # needed to download another run's artifact
124-
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.
127-
- uses: actions/download-artifact@v4
128-
id: download
129-
continue-on-error: true # no artifact when A's install failed: nothing to post
130-
with:
131-
name: commit-check-result
132-
run-id: ${{ github.event.workflow_run.id }}
133-
github-token: ${{ github.token }}
134-
- name: Post or update the PR comment
135-
if: steps.download.outcome == 'success'
136-
uses: actions/github-script@v7
137-
with:
138-
script: |
139-
// See examples/commit-check-workflow-b.yml for the full script
140-
const fs = require('fs');
141-
const prNumber = Number(fs.readFileSync('pr-number', 'utf8').trim());
142-
const body = fs.readFileSync('report.md', 'utf8'); // posted verbatim
143-
const MARKER = '<!-- commit-check-action -->';
144-
// Finds the comment that starts with MARKER and updates it,
145-
// or creates one when there is none yet
146-
```
147-
148-
> 📄 Full file: [`examples/commit-check-workflow-b.yml`](../examples/commit-check-workflow-b.yml)
149-
150-
### Key security benefits
46+
It reports as a check run, not as a comment. If your goal is "the contributor sees what
47+
failed, on the pull request, without me writing YAML", this is the shortest path.
15148

152-
- Workflow B runs in the **base repository's context**, so `GITHUB_TOKEN` has full write
153-
permissions (you explicitly grant `pull-requests: write`)
154-
- Workflow B **does not checkout the PR code**, so untrusted fork code never runs
155-
with elevated permissions
156-
- The artifact only contains `report.md`, `result.json` and `pr-number` — no code or secrets
49+
You can run the App and this action together: the App covers fork pull requests, the
50+
action gives you enforcement you control in CI, per-rule outputs for later steps, and
51+
`CCHK_*` overrides.
15752

158-
---
53+
### Or run on `pull_request_target`
15954

160-
## Option 2: pull_request_target (advanced, use with caution)
161-
162-
If you understand the security implications, you can use
163-
[`pull_request_target`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target)
164-
which runs in the base repository's context with **write token access**.
165-
166-
> **⚠️ Security warning:** Never check out (`actions/checkout`) the PR's HEAD commit
167-
> when using `pull_request_target`. Always check out the base branch or use the
168-
> default merge commit. Otherwise, fork code could exfiltrate your repository's secrets.
55+
If you cannot install a GitHub App — GitHub Enterprise Server, or an organization policy
56+
that forbids it — `pull_request_target` runs in the context of the base repository, so
57+
`GITHUB_TOKEN` has the permissions your workflow asks for and `pr-comments: true` works
58+
on fork pull requests.
16959

17060
```yaml
171-
name: Commit Check
172-
17361
on:
17462
pull_request_target:
175-
branches: ["main"]
63+
64+
permissions:
65+
contents: read
66+
pull-requests: write
17667

17768
jobs:
17869
commit-check:
17970
runs-on: ubuntu-latest
180-
permissions:
181-
contents: read
182-
pull-requests: write
18371
steps:
184-
# SAFE: checkout the merge commit, NOT the PR head
18572
- uses: actions/checkout@v7
18673
with:
74+
ref: refs/pull/${{ github.event.number }}/merge # the PR's commits
18775
fetch-depth: 0
18876
- uses: commit-check/commit-check-action@v2
18977
with:
@@ -192,9 +80,18 @@ jobs:
19280
pr-comments: true
19381
```
19482
195-
> ✅ With `pull_request_target`, `pr-comments: true` **does work** on fork PRs —
196-
> the token has the workflow's configured permissions regardless of whether the PR
197-
> is from a fork.
198-
>
199-
> **When to use this:** Only if the two-workflow pattern is too complex for your setup
200-
> and you have thoroughly reviewed the security implications.
83+
> [!WARNING]
84+
> `pull_request_target` grants a writable token to a workflow whose checkout contains the
85+
> fork's code. commit-check only *reads* commit metadata and never executes the checked-out
86+
> tree, but any other step you add to this job runs with that token. Keep the job to the
87+
> checkout and this action, never cache or build from it, and never expose secrets to it.
88+
> See [GitHub's guidance on `pull_request_target`](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/).
89+
90+
## What this page used to describe
91+
92+
Earlier versions documented a two-workflow pattern: workflow A runs the checks on
93+
`pull_request` and uploads an artifact, workflow B picks it up on `workflow_run` and posts
94+
the comment with a writable token. It worked, but it cost two workflow files, an artifact
95+
round trip, `actions: read`, and smuggling the PR number through the artifact — all to move
96+
information the contributor could already see into a comment. The App does the same job with
97+
no YAML at all, so the pattern and its example workflows have been removed.

0 commit comments

Comments
 (0)