What fallow posts on a pull request
Find the comment, check, review comments, annotations, job summary, SARIF and Code Quality output that fallow writes in CI, and how to turn each on.
A pull request has a fallow comment, a failed check and marks on some lines, and you must decide what to fix before the merge. The GitHub Action and the GitLab template write the result of one run to these places. This page shows each place with its real text, tells you how to read it, and names the input or variable that turns it on.
Each example on this page comes from one audit of a branch of the demo project. The branch adds the file src/services/cart-report.ts, with the unused export cartTotalCents and a 17-line block that two other files already have.
Each surface
Some surfaces are on by default, and others need an input, because they need a write permission. The table gives the state of each one:
| Surface | Platform | Default | Turn on or off |
|---|---|---|---|
| Sticky comment | GitHub, GitLab | Off | comment / FALLOW_COMMENT |
| Fallow check | GitHub | Off | comment |
| Review comments | GitHub, GitLab | Off | review-comments / FALLOW_REVIEW |
| Annotations | GitHub | On | annotations |
| Job summary | GitHub | On | Always written |
| SARIF in code scanning | GitHub | Off | sarif |
| Code Quality report | GitLab | On | FALLOW_CODEQUALITY |
The integrations analyze the project once and render each surface from that result. The comment and the review comments show the findings on the lines that the change adds. The clone group has three instances, but only the instance in cart-report.ts is on an added line, so the comment shows one duplication finding. To show more, set diff-filter (FALLOW_DIFF_FILTER) to diff_context, file or nofilter.
Sticky comment
Most reviewers read the comment first. The sticky comment is one comment on the pull request, and each run updates the same comment, so a pull request with ten pushes still has one fallow comment. When a pull request has no findings, fallow posts no new comment, and updates an older fallow comment to the clean result.
<!-- fallow-id: fallow-results -->
### Quality gate failed
Fallow audit report, 2 findings: 1 error, 1 warning.
> Gates: failed audit-verdict.
<details>
<summary>Dead code (1)</summary>
| Severity | Rule | Location | Description |
| --- | --- | --- | --- |
| error | [`fallow/unused-export`](https://fallow.tools/docs/explanations/dead-code/#unused-exports) | `src/services/cart-report.ts:25` | Export `cartTotalCents` is never imported by other modules |
</details>
<details>
<summary>Duplication (1)</summary>
| Severity | Rule | Location | Description |
| --- | --- | --- | --- |
| warning | [`fallow/code-duplication`](https://fallow.tools/docs/explanations/duplication/#clone-groups) | `src/services/cart-report.ts:7` | 17 lines repeat in 3 places (clone group dup:f42424e8) |
</details>
Generated by fallow.
Read the comment from the top:
| Part | Meaning |
|---|---|
<!-- fallow-id: fallow-results --> | The marker that fallow uses to find its comment again. Set it with comment-id (FALLOW_COMMENT_ID). |
| Heading | The verdict of the comment. See the table below. |
| First line | The report, the number of findings, and the count for each severity. |
Gates: | The result of each gate that the run turned on. |
| One block for each analysis | A table with the severity, the rule, the file and line, and a description. The rule links to its documentation. |
| Heading | When |
|---|---|
Quality gate failed | A finding has the severity error, or a gate failed. |
Review needed | All findings have the severity warn. The job passes. |
Quality gate passed | The run has no findings. |
An audit with the verdict warn thus shows Review needed, and its job passes. The example above shows Quality gate failed, because cartTotalCents is an error finding. When the author removes the export and pushes again, the same comment changes to Review needed.
A long comment can hide the heading below a large table. comment-layout (FALLOW_PR_COMMENT_LAYOUT) sets how much the comment shows:
| Layout | Content |
|---|---|
default | The heading, the summary, and one collapsed table for each analysis. |
details | The same tables, open. |
compact | The heading, the summary, and one row for each analysis with its error and warning counts. |
gate-only | The heading and the summary. Use it when the Fallow check is the main surface. |
By default, the comment also shows the project-level dependency findings, because they have no line in the diff. summary-scope: diff (FALLOW_SUMMARY_SCOPE: "diff") removes them from the comment.
Fallow check
The comment informs the reviewer. A branch protection rule cannot read a comment, but it can require a check. With comment: true, the action also posts a GitHub check named Fallow on the head commit of the pull request. The title of the check is the verdict with the counts. For the example branch, the title is Quality gate failed: 1 error, 1 warning. The conclusion is failure, neutral or success, in the same order as the headings above. To make each gate a separate required check, see fallow ci post-check-run --split-gates.
Review comments
The sticky comment lists the findings far from the code. Review comments put each finding on its line in the diff, where the author fixes it. With review-comments: true, fallow posts one review with a comment on each finding line. GitLab gets one discussion for each finding. When fallow can fix a finding, the comment has a suggestion block. This is the comment on line 25 of cart-report.ts:
**error** (introduced) [`fallow/unused-export`](https://fallow.tools/docs/explanations/dead-code/#unused-exports): Export `cartTotalCents` is never imported by other modules
**Fix:** Remove the export, or keep it when it is public API.
```suggestion
const cartTotalCents = (items: Item[]): number =>
```
<!-- fallow-fingerprint:v3: 26de96971de49534 -->
introduced marks a finding that the change adds. The suggestion removes only the word export, so the author can accept it with one click and keep the function. The fingerprint identifies the finding. When a later run does not report the finding again, fallow resolves the comment. max-comments (FALLOW_MAX_COMMENTS) limits the number of comments, with a default of 50.
Annotations
A pull request from a fork gets a read-only token, so the comment and the review comments fail there. Annotations still work. The action writes each finding as a GitHub workflow command, and GitHub shows it on the line in the Files changed tab. Annotations need no write token.
::notice::Fallow: Gates: failed audit-verdict.
::error file=src/services/cart-report.ts,line=25,col=14,title=Unused export::Exported value 'cartTotalCents' is never imported by other modules.%0A%0ARemove the export keyword or the declaration. If the export is public API, add its file to the entry configuration.
::notice::Fallow wrote 4 annotations. GitHub shows at most 10 of each level for each step.
An error finding becomes an ::error, and a warn finding becomes a ::warning. The run wrote 4 annotations, also for the two instances of the clone group outside the change: the annotations do not apply the diff filter of the comment. The sample above leaves out the three ::warning lines. max-annotations limits the number, with a default of 50. With review-comments: true, the action writes no annotations.
Job summary
The annotations mark single lines. For one view of the whole run, the action writes a summary to the page of the workflow run. It needs no write token. The summary starts with one row for each analysis:
## Fallow audit report
> [!CAUTION]
> **Audit failed**, 2 changed files
| Category | Findings | Introduced | Inherited |
|:---------|---------:|-----------:|----------:|
| Dead code | 1 | 1 | 0 |
| Complexity | 0 | 0 | 0 |
| Duplication | 1 | 1 | 0 |
| Styling | 0 | 0 | 0 |
Inherited counts the findings that existed before the change. With the default audit gate new-only, they do not fail the verdict.
SARIF in code scanning
The surfaces above belong to one pull request. Code scanning shows the alerts in the Security tab of the repository. With sarif: true, the action uploads a SARIF 2.1.0 file to GitHub code scanning with the category fallow. Each finding becomes an alert with the rule id, for example fallow/unused-export. GitHub Actions gives the setup and the permission.
Code Quality report
On GitLab, the Code Quality report takes the place of the annotations, and it needs no token. The GitLab template writes gl-code-quality-report.json in the Code Climate format. GitLab shows these findings in the merge request. The first entry of the file:
[
{
"type": "issue",
"check_name": "fallow/unused-export",
"description": "Export 'cartTotalCents' is never imported by other modules",
"categories": [
"Bug Risk"
],
"severity": "major",
"fingerprint": "26de96971de49534",
"location": {
"path": "src/services/cart-report.ts",
"lines": {
"begin": 25
}
}
}
]
Render a surface yourself
On another CI system, or with your own bot, you can post the same surfaces. Each surface is an output format of fallow. To build your own integration, render the format and post it with your own code:
npx fallow audit --base origin/main --format pr-comment-github
The formats are pr-comment-github, pr-comment-gitlab, review-github, review-gitlab, github-annotations, github-summary, sarif and codeclimate. fallow report renders each one from a saved JSON result. fallow ci posts a comment or a review with the same rules as the two integrations.
Related
- Next: GitHub Actions or GitLab CI. Turn on the surfaces that your team reads.
fallow report