/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Release Please

Keywords on this page
WordMeaningExample
Conventional CommitA commit title that starts with its kindfeat(twin): add floor picker
TypeThe kind of change, before the colonfeat, fix, chore
ScopeThe part changed, in bracketstwin, gateway
Breaking changeA change that needs users to adapt; ! after the type, or a BREAKING CHANGE: linefeat(gateway)!: drop /v1
ComponentOne package with its own versionbackend/chat, component chat
ManifestThe file that holds the last released version of each component.release-please-manifest.json
Release PRThe pull request Release Please keeps open with the next versions and changelogchore: release master
Pre-majorA version below 1.0.00.3.1-alpha
PrereleaseA version with a suffix that marks it unfinished-alpha

Release Please turns commit titles into version numbers and changelogs. Nobody picks a version by hand: the commits merged since the last release decide it. The tool runs in cd-release.yml on every push to master.

Related pages: GitHub Actions CI, commit scopes in Naming.


Files

FileHolds
.github/workflows/cd-release.ymlRuns googleapis/release-please-action with the two files below, token SEMANTIC_RELEASE_TOKEN
release-please-config.jsonOne entry per component: path, release-type, component, options
.release-please-manifest.jsonLast released version per path, written by the release PR
CHANGELOG.mdRoot changelog, one section per release
backend/digital-twin/CHANGELOG.mdThe only component changelog so far

Components

Pathrelease-typeVersion file it bumpsOwn tag and GitHub release
.simplenone, only CHANGELOG.md and the manifestYes: v0.3.1-alpha
frontendnodepackage.json, package-lock.jsonNo
backend/chat, notification, telemetry, socket, digital-twin, dashboardrustCargo.toml, Cargo.lockNo
backend/agentpythonpyproject.tomlNo
backend/claims-gateway, provisioner, registry, tenancy, backend/libs/*gonone: Go modules carry no version; only the changelogNo

Root options

OptionEffect
prerelease: true, prerelease-type: alphaVersions carry -alpha
bump-minor-pre-major: trueBelow 1.0.0, a breaking change bumps the minor, not the major
bump-patch-for-minor-pre-major: trueBelow 1.0.0, a feat bumps the patch, not the minor

From commit type to version

CommitAbove 1.0.0Root today, below 1.0.0
fix:patch: 1.4.2 → 1.4.3patch
feat:minor: 1.4.2 → 1.5.0patch: 0.3.0-alpha → 0.3.1-alpha
feat!: or BREAKING CHANGE:major: 1.4.2 → 2.0.0minor: 0.1.0-alpha → 0.2.0-alpha
docs, chore, ci, refactor, test, style, perf, buildnothingnothing
No type, or a typo like feet:nothing, no errornothing, no error

The highest bump among the commits wins.

Example, from CHANGELOG.md.

Which component a commit counts for

A commit counts for every component whose path holds a file it changed, and always for ..

Example. feat(twin): support multi-floor buildings changes backend/digital-twin/src/… and frontend/src/….

The scope in the title is only text for the changelog. Release Please picks components by file paths, never by scope.


The release flow

sequenceDiagram
    autonumber
    participant D as Developer
    participant M as master
    participant W as cd-release
    participant RP as release-please-action
    participant PR as Release PR
    participant G as ci-gate
    D->>M: squash-merge feat(twin): add floor picker
    M->>W: push event
    W->>RP: run with release-please-config.json and the manifest
    RP->>RP: per path, read commits since that path's last release
    RP->>RP: compute versions, write changelog entries
    RP->>PR: open or update chore: release master
    PR->>G: the PAT-authored PR starts ci-gate like any PR
    D->>M: merge the release PR
    M->>W: push event
    W->>RP: run again
    RP->>RP: finds its release PR merged and not yet tagged
    RP->>M: tag v0.3.2-alpha, GitHub release with the notes
    RP->>PR: relabel the PR as tagged
StepDetail
4The last release of each path is found through the merged release PR and the manifest
6One PR for all components, the Merge plugin. Title chore: release master. Its diff: CHANGELOG.md files, version files, .release-please-manifest.json
7Opened with SEMANTIC_RELEASE_TOKEN, a personal token: a PR made with the default GITHUB_TOKEN starts no workflows, and could never pass the gate
8A normal squash merge, so cd-registry also runs on it
11Only for .; components have skip-github-release

What each run decides

flowchart TD
    S["push to master"] --> A{"merged release PR without a tag?"}
    A -- "yes, and it is the latest" --> T["tag it, publish the release"]
    A -- "yes, an older one" --> X["abort: untagged, merged release PRs outstanding"]
    A -- no --> C{"any feat, fix or breaking commit since the last release?"}
    C -- yes --> P["open or update the release PR"]
    C -- no --> N["do nothing"]

Traps

Releases are stuck

Every cd-release run since release PR #337 ends with “There are untagged, merged release PRs outstanding – aborting”, and the job still shows green. #337 released only one component, at the old path backend/twin-service, and still carries the label autorelease: pending. That path is no longer in the config, so Release Please can never tag it, and waits for it on every run. No release PR has opened since. Changing the label of #337 to autorelease: tagged by hand unblocks it.