| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| save | ||
| action.yml | ||
| CHANGELOG.md | ||
| README.md | ||
once
Run a CI job's expensive part once per source tree.
A commit that fast-forwards from a PR to staging to main is the same tree
three times under three events, and every push re-ran typecheck, tests, lint,
or a twenty-minute Gradle build on content that had already passed. This
action keeps a cache marker keyed on the git tree hash and tells the job
whether that exact tree already passed. Content is what the gates validated,
so content is the key: a rebase that changes nothing is a hit, a one-line
change is a miss.
jobs:
checks:
runs-on: self-hosted
container:
image: git.bun.cafe/actions/node-docker:24
credentials: { username: ${{ github.actor }}, password: ${{ secrets.NPM_TOKEN }} }
steps:
- uses: actions/checkout@v4
- uses: actions/once@v1
id: once
with:
name: checks # one marker per name per tree
key: node24 # optional: what changes the outcome without changing the tree
- if: steps.once.outputs.passed != 'true'
run: npm ci
- if: steps.once.outputs.passed != 'true'
run: npm test
- uses: actions/once/save@v1 # last, and with no `if:` of its own
with:
name: checks
key: ${{ steps.once.outputs.save-key }}
How it is safe
actions/once only looks the marker up. The marker is saved by
actions/once/save, a step of the job itself, placed last. A workflow step is
skipped once an earlier step has failed, so a job that fails anywhere before it
saves nothing and the next run of the same tree starts clean. Without the save
step nothing is ever marked, and every run does the full work: forgetting it
costs time, never a false pass.
The save step takes the key from the save-key output, not from a file: a step
output cannot be changed by anything the job runs afterwards, and the save step
refuses a key that is not this name's.
Give the save step no if: of its own. if: always() or
if: steps.once.outputs.passed != 'true' would replace the implied "everything
so far succeeded" and mark trees whose job failed.
The save used to be actions/cache's post step inside this action, with
post-if: success(). On the Forgejo runner that condition is evaluated against
the steps of the composite action, which have all succeeded, not against the
job, so a failed job saved its marker and a re-run skipped the work it had just
failed. Markers written that way are discarded: the default version is now
v2.
That is also why the action must live inside the job it guards and gate
steps. A separate "gate" job would succeed trivially and mark a tree whose
real job then failed. needs: cannot express this; if: on steps can.
Inputs
| input | default | notes |
|---|---|---|
name |
checks |
what the marker certifies; a job with two independent expensive parts uses two names |
key |
'' |
extra key material: container image tag, toolchain version — anything that changes the outcome without changing the tree |
version |
v2 |
bump to invalidate every marker for this name |
paths |
'' |
only these paths count, whitespace-separated (a directory covers everything under it); see below |
ignore |
'' |
paths that do not count, whitespace-separated (a directory covers everything under it); see below |
Outputs
| output | value |
|---|---|
passed |
'true' when this tree already passed under this name, else empty |
tree |
the tree hash, or the listing hash when ignore is set |
save-key |
what actions/once/save saves the marker under; empty when the tree had already passed |
One marker per platform
A repo that builds several things from one tree — an Android app, a desktop
app, shared modules under both — rebuilds all of them for a change to any of
them under the whole-tree key. paths scopes a marker to what a build actually
reads, so each platform keeps its own marker and a change to one leaves the
others standing, across commits, not just across refs:
- uses: actions/once@v1
id: gates
with:
name: gates
paths: shared composeApp gradle gradle.properties settings.gradle.kts .forgejo/workflows/ci.yaml
- uses: actions/once@v1
id: android
with:
name: android
paths: shared composeApp androidApp gradle gradle.properties settings.gradle.kts .forgejo/workflows/ci.yaml
- if: steps.gates.outputs.passed != 'true'
run: ./gradlew :shared:jvmTest :composeApp:desktopTest
- if: steps.android.outputs.passed != 'true'
run: ./gradlew :androidApp:assembleDebug
- uses: actions/once/save@v1
with:
name: gates
key: ${{ steps.gates.outputs.save-key }}
- uses: actions/once/save@v1
with:
name: android
key: ${{ steps.android.outputs.save-key }}
The list is the transitive closure, by hand: the module, every module it depends on, the version catalog and wrapper, the settings file, and the workflow itself. A path left out is a change that ships unbuilt behind a stale marker, so keep two habits: every set includes the build files and the workflow, and a release build ignores markers entirely. A listed path that is not in the tree fails the step rather than hashing less. Inputs the build reads from outside the tree (a sibling repo cloned at a moving ref) are invisible to any key — the same as with the whole-tree hash.
Release commits
A release PR from actions/release-pr changes one file, CHANGELOG.md, and
nothing the gates read — yet it is a new tree, so it re-ran a full build and
attached an APK nobody wanted. ignore takes such paths out of the key:
- uses: actions/once@v1
id: once
with:
name: gates
ignore: CHANGELOG.md
With it set, the key is a hash of git ls-tree -r HEAD minus those paths
instead of the tree hash, so the release PR, the merge that lands it and the
commit it was cut from all share one marker. Keep it to files that truly do not
matter to the job; a path listed here can change without anything re-running.
What it does not do
- It does not skip the job's container start or its other caches; those are seconds. It skips what you gate.
- It does not know about outputs. A run that must produce an artifact (a release build on a tag) should run that step regardless and gate only the gates.
- A tree hash covers the whole checkout, workflow files included. Editing the workflow is a new tree, which is what you want.
Markers live on the shared actions-cache server (runner-pve), so a tree validated on one runner counts on every runner.