Docs
The four modes, the reference, recipes, the changes from v2 and the security documents.
Start
Modes
Mode commit
Builds, then commits the build output to the checked out branch and pushes it. This is the default mode and the original behavior of the action.
Mode check
Builds, then fails when the committed build output is stale. It pushes nothing.
Mode pr
Builds, then commits the output to a branch of its own and keeps one pull request up to date.
Mode build
Builds and checks that the output exists. It pushes nothing.
Reference
Guides
Recipes
Short answers for the setups that come up most. Each workflow below is checked against action.yml by tests/docs-examples.py: the inputs exist, the modes are valid, and the permissions and the…
Example workflows
Complete workflow files. Copy one to .github/workflows/ in your repository and change the build script and the paths. More setups, such as private registries, pnpm and yarn, tag events and Bitbucket…
FAQ
Short answers, each taken from a page of this documentation. Every answer ends with the page that has the details.
Testing
How to test the action locally and what CI runs. This page describes the v3 composite action on main. The Docker based scripts of v2 are gone, they stay in the v2 tag.
From v2
Breaking changes, v2 to v3
What breaks when you change @v2 to @v3, in one place. This page is the short form. The steps, the warnings that each renamed input prints and a before and after workflow are in the migration guide.
Migrating from v2 to v3
v3 keeps the idea of v2: build the project and commit the build output for you. It changes how the action runs, how it uses the token, and how it names its inputs. This page lists what to change,…
Security
Security
This action holds a write token and runs your build command, so a security problem can change your repository. This page says how the token is handled, links the documents that go deeper, and says…
Architecture
This page explains how the action is split into scripts, and which rules keep the write token away from the project's code. The rules are checked by tests/architecture.bats, so a change that breaks…
Threat model
This file describes what can go wrong with the action, what protects against it today (v2), and how the v3 design (#10) changes it.
Security audit, 2026-11-12
First written audit for issue #11. It covers main at commit ebdbe19 (after PR #23). Two findings (F7 and F13) were fixed by PR #24 after the audit and are marked in the table. Every statement has a…