- JavaScript 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| dist | ||
| src | ||
| test | ||
| .gitignore | ||
| action.yml | ||
| CHANGELOG.md | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
release-pr
Maintains a release pull request from conventional commits, then tags and publishes the release when that PR merges. The release-please model, implemented against Forgejo's own API.
jobs:
release:
runs-on: self-hosted
container:
image: node:24-bookworm
steps:
- uses: actions/release-pr@main
id: release
with:
token: ${{ secrets.RELEASE_BOT_PAT }}
version-file: package.json
Two things happen, both from the same invocation on a push to the default branch:
| tip of the default branch | what runs |
|---|---|
| ordinary commits | opens or amends the release PR |
chore(release): v1.2.3 |
creates the tag and publishes the release |
Merging the release PR lands that release commit, which triggers the second row. So merging is the release, and it's the only human act in the loop.
Why not release-please itself
release-please builds its release commit out of the low-level git write endpoints, and Forgejo does not implement them:
| endpoint | this instance | release-please needs |
|---|---|---|
/git/trees/{sha} |
GET |
POST |
/git/commits/{sha} |
GET |
POST |
/git/refs |
GET |
POST |
Its commit-history traversal is also a GitHub GraphQL query
(query pullRequestsSince), and Forgejo has no GraphQL API at all.
There is a third-party fork chain that does work —
gitea-release-please-action → @joaquinjsb/release-please →
@joaquinjsb/code-suggester — which swaps the write endpoints for
isomorphic-git against a local clone and the GraphQL query for REST
listCommits. It was evaluated and rejected: all three repos last saw a commit
in September 2025 with 3, 1 and 0 stars, the base is a patch line on top of an
upstream 16.15.0 that has since moved to 17.x, the committer is hardcoded to
Gitea Actions [Bot] <noreply@gitea.com>, and it commits by git push with
username/password — the exact path promote-staging.yaml documents avoiding in
this environment ("no git push, so no email-vs-uid resolution issues").
This action writes through the Contents API instead, the same mechanism tofu-apply's auto-paste uses.
Versioning
Bumps follow conventional commits: feat → minor, fix/perf/refactor/
docs/ci/build/test/chore → patch, ! or a BREAKING CHANGE: footer →
major. BREAKING CHANGE in a subject does not count, so describing a breaking
change cannot mint a major release.
Below 1.0.0 a breaking change bumps the minor rather than jumping to 1.0.0.
Semver treats 0.x as unstable and reaching 1.0.0 should be deliberate, not a
side effect of a ! in a commit message.
Non-conventional commits are ignored rather than rejected — merge commits and pre-convention history are both legitimate, and about 11% of the history in these repos does not conform.
Skipped types
skip-types defaults to auto,deploy, because both are bot commits here:
auto: is a doc refresh or plan paste, deploy: is an image pin bump. They
parse as valid conventional commits, so without this every bot push would cut a
release. They are also excluded from the changelog. A real commit alongside them
still releases normally.
A repo where deploys are the content can narrow the list (e.g.
skip-types: auto): un-skipped deploy commits then mint a patch and render
under a Deployments changelog section, like any other type.
Tags, and what earns retention
Merging produces v1.2.3, and actions/docker-buildx expands a refs/tags/v*
push into v1.2.3 v1.2 v1 latest. That matters beyond tidiness: the container
cleanup rule removes versions older than 14 days that are not otherwise kept, and
latest is always kept. Set Keep versions matching: ^v on the package to
cover the rest.
This is the failure this whole path exists to prevent — convex-backend had a
pin that gitops never advanced, and the orphaned version aged past 14 days and
was removed while a deployment still referenced it.
Inputs
| input | default | notes |
|---|---|---|
token |
— | required; write access to contents, pull requests and releases |
default-branch |
repo default | branch releases are cut from |
release-branch |
release/next |
long-lived head branch for the release PR |
changelog-file |
CHANGELOG.md |
its section for the version becomes the release notes |
version-file |
(none) | package.json gets its version rewritten; anything else holds the bare version |
skip-types |
auto,deploy |
types that never earn a release |
initial-version |
v0.1.0 |
used when there is no release tag yet |
labels |
release |
applied to the release PR |
committer-name / -email |
(unset) | unset means the token owner, not a hardcoded bot |
dry-run |
false |
compute and log, write nothing |
Outputs: version, tag, released, bump, pr-number. Gate a publish step on
released == 'true'.
The token
Use a bot PAT, not the automatic run token. Forgejo may not dispatch workflow
events for pushes made with the run token, which would mean the tag lands and no
build fires. promote-staging.yaml uses STAGING_AUTOPROMOTE for the same
reason.
Scopes: write:repository covers contents, pull requests and releases.
Release notes come from the file
The notes published with the release are read back out of CHANGELOG.md rather
than regenerated from commits. If someone edits the changelog on the release
branch before merging, that edit is what ships — the PR is a real review surface,
not a preview.
Idempotency
Every step is safe to re-run. The changelog section for a version is replaced
rather than appended, so amending the PR on each push does not stack duplicates.
A release whose tag already exists is a no-op with released=false, so a
re-delivered push cannot double-publish.
An open release PR has the base merged into its head on each run, so its diff stays limited to the release changes instead of accumulating everything that has landed since the branch was cut.