No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 03:40:19 +00:00
.forgejo/workflows ci: bot identity -> system service user [skip ci] 2026-11-16 22:40:16 -05:00
save fix: the save step takes its key from the lookup's output and refuses any other 2026-11-16 12:38:00 -05:00
action.yml fix: the save step takes its key from the lookup's output and refuses any other 2026-11-16 12:38:00 -05:00
CHANGELOG.md chore(release): v1.2.1 2026-11-16 17:40:02 +00:00
README.md port to git.bun.cafe: default server URL, registry, bot email, runner label 2026-11-16 17:15:10 -05:00

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.