Releasing
Merging and releasing
PRs are squash-merged with one commit each. To keep the commits of a large integration branch,
push them to a history/ branch first, from the branch being merged:
git push origin HEAD:refs/heads/history/my-integration
Link that branch in the PR before squashing. Keep the archive when deleting the working branch.
Merging to main does not publish a release. The maintainer opens Actions → Release → Run
workflow, selects main, and chooses the version bump. auto reads conventional commits,
including ! and BREAKING CHANGE: markers in the squash message. Select Dry run to build
the candidate package without publishing tags, images, packages or docs.
A real release runs CI, builds the app images, renders a CPU smoke film in the exact amd64 image, and publishes the tested multi-architecture image before the GitHub release and PyPI packages. The package build must also pass before the Git tag is pushed. Release runs execute one at a time.
Images without a release
For a merged container fix, dispatch Actions → Release → Run workflow on main and select
app_only. It runs CI, builds the main/render app image for both architectures, and renders
the smoke film before publishing ghcr.io/sam-dumont/immich-memories:sha-<12-character-commit>.
Pin that image by digest in your deployment.
Select inference_only instead for the standalone inference images. Choose one image-only
mode per run. These modes publish commit tags; they create no GitHub or PyPI release, do not
move latest, and do not deploy the docs site.
Nightly builds
Actions → Nightly builds main every day at 03:17 UTC, but only when main has commits since
the last nightly. The marker is the Commit: line in the body of the rolling nightly GitHub
prerelease, written last; a run that failed half-way leaves the old one, so the next run tries
again. A day with nothing new ends green with "Nothing new on main" in the run summary.
To start one by hand, run the workflow on main. Tick force to build an unchanged main.
A forced nightly is the pre-tag rehearsal: it builds and smoke-tests everything a release does
without opening the RC series.
The nightly workflow only makes that check. The build is the Release workflow itself, called
with channel nightly: the same jobs in the same order (images by digest first; nothing public
until the wheel built and the app image passed its smoke film), after CI and the real-Immich gate
ran in full, as for every release. It publishes:
| Nightly | |
|---|---|
| Version | a dev version after the last release, 1.0.1.devYYYYMMDD after 1.0.0, 1.0.0rc9.devYYYYMMDD after 1.0.0-rc.8, shown by immich-memories --version |
| App image | :nightly and :nightly-YYYYMMDD, amd64 and arm64 |
| Inference images | :nightly, :nightly-YYYYMMDD and their -cuda twins, rebuilt only when something the inference image copies in changed; otherwise the previous nightly's images get the new date tag |
| GitHub release | one prerelease named nightly on the nightly tag, replaced each run, never "Latest". Wheel, sdist, provenance, Compose files pinned to nightly-YYYYMMDD, deployment bundle, installation.json, SHA256SUMS |
PyPI, latest, v* tags | never touched |
| Docs site | /dev/ |
Image Maintenance deletes image versions whose only tags are nightly-YYYYMMDD dates older
than 14 days. It never touches nightly, version tags, latest or commit builds.
The nightly runs without the production environment approval, since nobody is awake to give
it. Everything else is the release's own jobs: provenance on the wheel and every image, and
the same packaging for the setup files. Release dispatches offer only stable and rc.
Run the first-install checks against a forced nightly's public files and images. Record the anonymous pulls, the exact host, service and Immich versions, cold or warm state, and the playable film each one made: a published artifact that nobody installed proves nothing. After tagging a candidate, check its real tags and links, and rerun the lanes whose artifacts differ from the nightly's.
Release candidates
The Channel input picks what a run publishes. stable (the default) is a final release; rc
is a release candidate, tagged vX.Y.Z-rc.N.
- Open a series. Run with channel
rcand choose the version bump for the candidate series. The workflow calculates and displays the candidate tag. - Fix and repeat. Merge fixes to
main, then run with channelrcagain:v1.0.0-rc.2,rc.3and so on. The bump input is ignored while a series is open. A run with no commit since the last candidate fails instead of publishing a duplicate. - Promote. Run with channel
stable. It publishesv1.0.0frommain, with notes covering the candidate series. The run fails ifmaingained afeat,fix,perf,refactor,build,revertor breaking commit since the last candidate: that code was in no candidate, so cut one more first. Docs, tests, CI and chores do not block promotion.
A candidate goes through the same CI, smoke film and approval gates as a final, and differs in what it moves:
| Candidate | Final | |
|---|---|---|
| GitHub release | marked pre-release, not "Latest" | marked "Latest" |
| App image | :1.0.0-rc.1 only | :1.0.0 and :latest |
| Inference images | :1.0.0-rc.1, :1.0.0-rc.1-cuda | also :latest, :latest-cuda |
| PyPI | 1.0.0rc1, installed only with pip install --pre | default install |
| Docs site | root before the first 1.x final; /next/ afterward | root |
Testers pin the exact candidate tag. Candidates do not move latest; a final release does.
Release notes
The workflow writes a plain commit list as the release body. A final release gets notes written by hand instead, in the format the Immich app uses, and they replace that body once the release exists. The notes cover what changed since the previous published release (for 1.0.0, since rc.10), because that is what someone upgrading reads.
-
Write the highlights in a Markdown file, in the docs' voice (Writing the docs):
- a
> [!WARNING]box first, when upgrading needs an action: one line per change, linking the matching section ofrun/maintenance/upgrading.md; - a welcome line: what the app makes, and what these notes cover;
## Highlights: a bulleted list, then one###section per highlight, a few sentences and a screenshot fromdocs-site/static/img/screenshots/when the change shows in the UI.
Take the highlights from
git log <previous>..main(feat,perfand user-visiblefixcommits) and check every claim against the code, the same way a docs page is checked. - a
-
Add the changes with the script. It groups every commit under Immich's headings (security, features, performance, bug fixes, docs, cleanup, dependencies, build/CI/tests), links each to its pull request and ends with the full-changelog link:
uv run python scripts/release_notes.py v1.0.0-rc.10 v1.0.0 --highlights highlights.md > notes.md -
Check it:
uv run python scripts/private_terms_gate.py --require-terms --text-file notes.md. -
After the release run publishes, replace the body:
gh release edit v1.0.0 --notes-file notes.md
Docs tracks
Pages serves one site, so every deploy (a release, a nightly or a manual Deploy Docs run) rebuilds all of it, each part from its own ref:
| Path | Track | Built from |
|---|---|---|
/ | stable | the newest final release; before the first 1.x final, main's current commit, labelled with the newest release candidate |
/next/ | next | the newest release candidate, only when it is newer than stable |
/dev/ | dev | the commit of the latest nightly |
scripts/docs_release.py picks the refs from the published GitHub releases and the nightly
marker. A release deploy rebuilds the current dev tree from the nightly's commit; a nightly
deploy rebuilds stable and next from their refs. /next/ and /dev/ are kept out of
search and carry a banner linking back to the stable docs.
Before 1.0 the candidate is the release, and its docs keep being finished on main after the tag (install paths, first-run fixes, the privacy page). Built from the tag's tree, the root would hide every one of those until the next candidate, so it follows main until the first 1.x final.
The three trees share large media. A static file over 256 KB whose bytes match the stable ref's
copy is linked from the root tree, and the /next/ or /dev/ copy is dropped at assembly; a
file that differs keeps its own copy. Media components resolve paths with useMediaUrl, not
useBaseUrl, so they pick the shared copy. The deploy prints each tree's size and fails when the
whole site passes 900 MB, under the 1 GB Pages limit.
The files people copy from main (the Unraid template, the Compose files, example.env, the
README download recipe, the Kubernetes and Terraform image tags) name the last published release,
never latest. Nobody pins them by hand: the pre-commit hook runs make pin-latest, so the first
commit after a release moves every pin to it and stops, like a formatter; stage the files and
commit again. The hook reads the tags on origin, since CI tags the release and a clone may not
have it yet. A release refuses to start while main still pins an older one
(release_pin.py --check). The /dev/ docs are built from a nightly's tree, so the deploy pins
that tree to the nightly's own images before building; nothing is committed for that. A test
fails if any pinned file says latest or the pins disagree. The pin also points the README's
browser URLs at the host port of the Compose file that release ships. The release assets are
stamped with their own version regardless.
CI uses make secret-scan for both PRs and release runs: all commits since the latest version
tag, or all history for the first release. It also catches secrets removed by a later commit in
that range. Install Gitleaks 8.24.3 to run the same scan locally; pre-commit uses that version too.
Household validation before release
Before tagging, validate the exact commit against the private test households. Check people and groups, selection, titles, wording and the celebrations that apply, including the cases where no film is the right answer. Report the tiers you actually checked: an older report does not validate a new commit.
Private validation media and detailed reports stay private. Publish only anonymous aggregate results. Public screenshots and demos use the separate demo fixture library.
The private households do not cover every family or culture. Contributor examples help extend that coverage; see Households and cultures.
Private terms gate
make privacy-gate blocks owner-defined private terms (family names, birth dates, GPS
coordinates) from diffs, commit messages and PR titles. Two pre-commit hooks run it as well.
The denylist never lives in this repo. It resolves from, in order: --terms-file, an env var named
by --terms-env (how CI reads the PRIVATE_TERMS secret), $IMMICH_MEMORIES_PRIVATE_TERMS (a
path), or ~/.config/immich-memories/private-terms.txt. One term per line, # comments ignored, a
re: prefix for a regex. With none of those configured the gate prints a notice and exits clean,
which is the normal case for a contributor. Matches are masked to their first character, so a hit
report never contains the term it found.
Build versions
Release builds stamp the selected version into the wheel, container labels and docs.
The app displays the packaged server version. Docs show their build version in the
navigation, footer and page metadata; /next/ also includes it in the banner.
Release candidates keep their exact vX.Y.Z-rc.N tag. Unreleased builds include
the source commit, and version discovery ignores the separate models-v* tags.
Repository name and search indexing
The repository is sam-dumont/immich-memories. The package and command remain
immich-memories. Container images use ghcr.io/sam-dumont/immich-memories
and ghcr.io/sam-dumont/immich-memories/inference. CPU tags are X.Y.Z and
latest; CUDA inference tags add -cuda. Model downloads use the renamed
repository with the same release tags, filenames and checksums.
A repository rename does not copy container tags. Run Migrate Container Images
on main to copy the existing 0.103.0 app, inference CPU and inference CUDA
manifests to the new packages, including their latest aliases. The workflow
checks source and destination digests and refuses to replace a different image.
It shares the release publication lock, so it cannot race a release.
After the first copy, set both new container packages to Public in their GitHub package settings, then check that they can be pulled without signing in. GHCR creates new packages as private, even for public repositories. GitHub package visibility.
Old container packages remain available for existing installations and historical releases. To switch an installation, download the current Compose files or change its image repository to the new name, keeping its version tag. Historical build attestations retain the original repository and signer identity; copying an image does not create new build provenance. See Security.
Before the next PyPI release, check the trusted publisher for both
immich-memories and immich-memories-music: owner sam-dumont, repository
immich-memories, workflow release.yml, environment pypi. Replace the old
publisher after adding the new one. PyPI publisher setup.
The free docs address is https://sam-dumont.github.io/immich-memories/.
Docusaurus renders HTML, canonical links and sitemap.xml; each production build
checks the sitemap pages. Docs under /next/ and /dev/ are marked noindex.
To verify indexing in Google Search Console:
- Add a URL prefix property for
https://sam-dumont.github.io/immich-memories/. - Choose HTML tag verification. Save just the tag's
contentvalue as the GitHub Actions repository variableGOOGLE_SITE_VERIFICATION. - Run Deploy Docs on
main, then click Verify in Search Console. Keep the variable for future builds. - Submit
https://sam-dumont.github.io/immich-memories/sitemap.xml. - Inspect the homepage and quick-start URL, run the live test, and request indexing. Check the Page indexing report after Google has crawled them.
A robots.txt inside this project's subdirectory would not control crawling:
Google reads it at https://sam-dumont.github.io/robots.txt. No file is required
to allow crawling. Google's robots.txt rules.
GitHub redirects old repository links, but not the old Pages path. Update links you control. Do not recreate the old repository to host redirects: it would replace GitHub's repository redirects. Preserving the old docs paths needs a separate redirect setup at the account site. GitHub rename behavior.
Google decides whether and when to index a page. Submitting a sitemap or an indexing request does not guarantee inclusion or ranking. The GitHub repository itself is on GitHub's domain; this Search Console property covers the docs only.