Releasing¶
For maintainers: how a release of this repository is cut, how CHANGELOG.md is kept, and how the images and the Helm chart are published. The tags themselves, and what each image is: Images.
Releases¶
A release is a GitHub release with a calendar version, vYYYY.MM.DD, and .2, .3... for another one the same day. Its tag is on a commit of the default branch. It does not build anything: it names the images the default branch published (and tested) at that point. The image tags stay those of the upstream versions (syncstorage-rs-mysql-0.24.1, fxa-mono-v1.349.0, the dated ...-<release>-<build date>, see Images); the chart's appVersion comes from them too.
release.yml cuts one, with release.py, in two cases:
-
A tag we push. Tag a commit of the default branch that was the head of a push (it has its CI runs), or a merge of a dependency update (the gate started its CI by hand, Dependency updates), and push the tag:
git tag v2026.11.09 <commit> git push <remote> v2026.11.09The workflow refuses a commit that is not on the default branch, waits for every CI run of that commit, and releases once all of them passed; one that failed, or no run of the default branch (a push, or a manual run), fails it with the reason.
-
After the weekly runs. Once the scheduled runs of syncstorage-rs.yml and fxa.yml both completed, there is a release only if something is new since the previous release: the syncstorage-rs, accounts (mozilla/fxa) or pairing server version of the published images, or the upstream patches applied to them (the
org.firefox-sync.upstream-patcheslabel), or entries under Unreleased in CHANGELOG.md. Otherwise the run says why there is none (nothing new since v2026.11.02: ...). The tag goes on the commit the weekly runs built. The first run without any release of this kind before releases.
The release:
- the title
vYYYY.MM.DD — syncstorage-rs X.Y.Z, accounts vA.B.C; - the notes: the entries of Unreleased (under Changes, the empty subsections left out), then Upstream: each version with links to Mozilla's release notes of every release since the previous one, the compare link, and syncstorage-rs' CHANGELOG.md with the diff of that file between the versions; the upstream patches applied; then the image tags with their dated build tag and digest, and the chart version when the chart of that commit is published. At the end an HTML comment,
release-state, records the versions and patches: the next run compares with it; - then CHANGELOG.md: the entries released move into a section
## vYYYY.MM.DD — YYYY-MM-DDunder Unreleased, which keeps its subsection headings and nothing else (a release without entries gets a line with the upstream versions). A commit ofgithub-actions[bot]with[skip ci]on the default branch, so no workflow runs for it. Entries added after the commit released stay in Unreleased.
Only that last job, publish, can write (contents: write); the decision runs with read access.
A copy of the repository that must never release (a development repository that is fast-forwarded into this one) sets its repository variable FFS_RELEASES=off: release.yml still decides and prints the notes, and publish is skipped, so no tag, release or CHANGELOG.md commit is made there.
To see what would be released now, without releasing:
GITHUB_REPOSITORY=<owner>/<repository> GITHUB_TOKEN="$(gh auth token)" \
python3 -I .github/scripts/release.py plan --event manual --dry-run
python3 -I tests/test_release.py
On every push to another branch than the default one, release.yml runs that dry run and prints the notes. By hand, Run workflow on the default branch with dry_run off decides as the weekly run does, without waiting for it. The token needs to read the packages (read:packages) for the image tags and labels.
The changelog¶
CHANGELOG.md is what changed for those who run firefox-sync, written for them, not a list of commits. A branch that changes something they see adds its entry under ## Unreleased, in the subsection it belongs to:
## Unreleased
### Breaking
- `SYNC_DB_URL` is now required: set it before upgrading (see docs/upgrading.md).
### Added
### Changed
### Fixed
- The admin UI's storage report counted deleted collections.
### Security
An entry is a list item (more lines indented under it), and HTML comments are not entries. Upstream releases need no entry: the release lists them. tests/check_docs_changed.py warns on a branch that changes a feature without a new entry under Unreleased (Testing). When a change needs none (a refactor, the tests, CI), say so on a line of its own in a commit message of the push:
Changelog: none (a refactor of the alert code)
The images¶
Every image is published to ghcr.io/<owner>/<repository> only after its tests passed with it (Testing), and only from the default branch. A branch builds and tests, under tags of its own.
| Image | Workflow | When | Published as |
|---|---|---|---|
| Sync server and its init images | syncstorage-rs.yml | every Monday from syncstorage-rs' newest release, and on every push but docs-only ones | the per-architecture tags, then the multi-arch -latest, -<release> and -<release>-<build date> |
| accounts and pairing server | fxa.yml | every Monday from the newest mozilla/fxa release, on a change of the workflow or of the upstream patches, or by hand (version, rebuild) |
tags of the run, tested by digest, then the multi-arch tags from those digests |
| admin UI | admin.yml | every change of admin/ |
the candidate admin-<sha12>, tested as published, then tagged admin-latest. A newer push cancels an older run, so an older candidate never overwrites admin-latest |
- syncstorage-rs.yml reuses an identical image instead of building it again. Its key tag (
syncstorage-rs-<image>-key-<key>-linux-<arch>) names every input: for the Sync server the upstream tag,APP_BUILD_REVISION, the patches applied (and the files of their ports), and a hash of what of this repository goes into the image (the scripts that change the sources, upstream-patches.py and syncstorage-rs-build.py, and the build arguments); for an init image the content of its directory. Main writes its key tags, the per-architecture tags and the build cache; a branch writes key tags of its own (-key-<key>-ref-<branch>-...) and reuses main's image of the same key too, read only, so a branch builds only the images its change touches. The weekly run and a manual run withrebuildstart from scratch, to pick up the base images' security updates. BumpAPP_BUILD_REVISIONin the workflow when the way the image is built changes there (the platforms, a step before the build). - The Sync server's compiled dependencies are a layer of the build cache: upstream's Dockerfile cooks them first with cargo-chef, from a recipe of
Cargo.lockand the manifests, and syncstorage-rs-build.py drops its cache mounts (empty on every new runner, and not in a registry cache), so that layer keeps them. While the recipe is the same, only syncstorage-rs' own crates compile. The cache is main's (buildcache-syncstorage-rs-<image>-<release>-linux-<arch>,mode=max); a branch reads it, and writes one of its own (...-<release>-ref-<branch>-linux-<arch>) for the Sync server images it builds. The weekly run deletes the caches older than 6 days. - On a branch, a newer push cancels the older run of syncstorage-rs.yml, fxa.yml and helm.yml: only the latest commit of a branch is tested. Runs of the default branch and the scheduled ones always finish. A tag (a release, a chart version) builds no image.
- None of these workflows makes a GitHub release: Releases are release.yml's.
The Helm chart¶
helm.yml publishes the chart on a tag chart-v<version>, the version of Chart.yaml, after every test of the workflow passed.
- Set
versionin Chart.yaml. - Tag the commit
chart-v<version>and push the tag.
What the workflow checks and does:
- chart-version.sh refuses a tag that is not
chart-v<version>. A stable version must come from a commit of the default branch. A pre-release (0.1.0-dev.1) can come from any branch, to test the publishing:helm installwithout--versionor--develnever picks one. - A version is published once, never replaced: chart-unpublished.sh fails when the registry has it, or does not clearly answer that it is missing.
- The chart goes to
oci://ghcr.io/<owner>/<repository>/charts/firefox-sync(for this repositoryoci://ghcr.io/porelli/firefox-sync/charts/firefox-sync).Chart.yaml's annotationorg.firefox-sync/chartis set to that address: the admin UI'shelm upgradecommands show it, with the release's--version. - The publish job holds
packages: write, so it pins its third-party action (azure/setup-helm) by commit, and its Helm to one version (PUBLISH_HELM_VERSION), checked against that release's sha256. The other jobs use tags, and the latest Helm: move the publish job's to a version they passed with.
Package visibility¶
A new package starts private on GitHub. Make it public once, in the package's settings.