Inputs and Flags

Every action input maps to a CLI flag of the same name.

- uses: orochibraru/releaser@v1
  with:
    branch: main
    rules: ""
    prepare: ""
    commit: ""
    artifacts: ""
    docker: false
    docker-image: ""
    docker-platforms: ""
    draft: false
    prerelease: ""
    release-pr: false
    dry-run: false
    token: ${{ github.token }}

Input / flag	Default	Description
`branch`	`main`	Branch to release from. Any other branch is a no-op.
`rules`	—	Bump overrides, e.g. `breaking=patch,feat=patch`. See Versioning.
`prepare`	—	Shell command run before the release commit. `${version}` is replaced with the new version, e.g. `1.2.3`. Only `CHANGELOG.md`, `package.json` and `commit` files are committed. It doesn't see `GITHUB_TOKEN` or `GH_TOKEN`; pass what it needs under another name.
`commit`	—	Extra files for the release commit, comma separated. `CHANGELOG.md` and `package.json` (when present) are always committed.
`artifacts`	—	Enables artifact mode. `path[=name]`, comma or newline separated.
`docker`	`false`	Enables Docker mode.
`docker-image`	`ghcr.io/<owner>/<repo>`	Image to push.
`docker-platforms`	—	e.g. `linux/amd64,linux/arm64`.
`draft`	`false`	Create the GitHub release as a draft, assets still attached. Publish it yourself (`gh release edit`).
`prerelease`	—	Ship every push as `X.Y.Z-<id>.N`: tag and GitHub prerelease, no commit. See Canaries and release PR.
`release-pr`	`false`	Open or update a release PR instead of committing; merging it releases. See Canaries and release PR.
`dry-run`	`false` in CI	Only print the next version and notes. The CLI defaults to `true` when `CI` is unset.
`token`	`github.token`	Action only; the CLI reads `GITHUB_TOKEN` or `GH_TOKEN`. Used for the release, uploads, the release PR and the ghcr.io login.

#Outputs

Output	Example	Description
`released`	`true`	`false` when nothing shipped, dry runs included.
`version`	`1.2.3`	The version released, or that a dry run would release.
`tag`	`v1.2.3`	Same as `version`, with the `v`.
`prerelease`	`false`	`true` when `version` is a prerelease (`1.2.3-canary.4`).

Case	`released`	`version`
released (stable or canary)	`true`	set
dry run with a release pending	`false`	set
release PR updated, no canary this push	`false`	empty
nothing to release, or wrong branch	`false`	empty

- id: release
  uses: orochibraru/releaser@v1
- if: steps.release.outputs.released == 'true'
  run: echo "shipped ${{ steps.release.outputs.tag }}"

#Reading the version first

A dry run sets version and tag without touching anything, so a job can stamp images or binaries with the upcoming version before the real release:

- id: next
  uses: orochibraru/releaser@v1
  with:
    dry-run: true
# steps.next.outputs.version: the upcoming version, empty if nothing to release

Pass the same rules, prerelease and release-pr as the real run, or it computes a different version. With prerelease or release-pr, which version it reports is in Canaries and release PR.

#Environment

The CLI reads the usual Actions variables, so it behaves the same inside the action or as a plain run: step:

Variable	Used for
`CI`	Unset → dry run by default.
`GITHUB_TOKEN` / `GH_TOKEN`	GitHub release, uploads, release PR, ghcr.io.
`GITHUB_REF_NAME`	Current branch (falls back to `git`).
`GITHUB_REPOSITORY`	`owner/repo` (falls back to the `origin` URL).
`GITHUB_SERVER_URL`, `GITHUB_API_URL`	GitHub Enterprise Server, Gitea.
`GITHUB_ACTOR`	ghcr.io login username.
`GITHUB_OUTPUT`	Where the outputs above are written.

Gitea Actions sets these to the Gitea instance, and the release and the release PR go through endpoints Gitea shares with GitHub. Gitea's pull request list ignores the head and base filters, so releaser pages through the open pull requests and picks the one from this repository's release branch into branch itself. Artifact uploads are untested on Gitea.

← Previous

Getting Started

Migrating from semantic-release

This guide lives in the project repo: edit it there, and this page follows with the next release.