Release a Drift Docker image
Use this guide when publishing the reviewed v0.2.0 Docker image to GHCR. The process ties an immutable source tag to verified multi-architecture artifacts and provenance. Drift publishes Docker images only; it does not publish an npm package or client SDK in this release.
Prepare the release
Confirm the version is 0.2.0 in package.json and package-lock.json, and
review the dated v0.2.0 section of CHANGELOG.md. Then complete the service verification steps in
build Drift from source. That tutorial
is the source of truth for local install, build, CLI, site, and Pages
verification commands. Review the site dependency audit and require the
PostgreSQL 16, 17, and 18 CI jobs and both container smoke tests to pass.
Push the reviewed main branch and wait for the Verify workflow to pass. Do
not create a release tag from an unverified commit.
Release readiness, version selection, changelog meaning, compatibility, and rollout timing require maintainer approval. Automation may compare explicit version strings, run checks, build from the approved tag, and publish configured artifacts; it must not infer that passing checks makes a release appropriate.
Publish the tag
Create an annotated tag whose version exactly matches package.json, then push
that tag:
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0
The Release container image workflow reruns verification, builds
linux/amd64 and linux/arm64 images, publishes v0.2.0 and latest, attaches
build provenance, and creates a GitHub release titled Version 0.2.0 with the
manifest digest. Release tags use vX.Y.Z; titles use Version X.Y.Z.
Recover a failed tag release
Release tags are immutable. If a tag-triggered workflow fails before publishing,
do not delete, move, or recreate the tag. Fix the workflow through a pull request,
then open Actions → Release container image → Run workflow. Enter the existing
tag, such as v0.2.0, in the required tag field.
The manual run verifies the selected tag in every Verify job, confirms that
its package.json version matches the tag, and builds from the tagged commit.
It then performs the same image publication, provenance, and GitHub release
steps as a tag-triggered run.
Verify package visibility
Confirm that ghcr.io/grey-harbor/drift remains public in GitHub package
settings. Repository visibility does not by itself establish package visibility.
Verify the result from a clean environment:
docker pull ghcr.io/grey-harbor/drift:v0.2.0
docker buildx imagetools inspect ghcr.io/grey-harbor/drift:v0.2.0
The inspection must list both Linux platforms. Record the release digest in deployment configuration when an immutable production pin is required.
Roll out and observe
Roll out the immutable digest to a non-production environment first. Verify the
container health status, /health, startup logs, tenant authentication, and
representative reads and writes against an operator-approved dataset. Retain the
prior digest and take a verified database backup before updating a deployment.
For an SQLite-to-Postgres cutover, use the separate
PostgreSQL migration procedure; it requires stopped writes and an
empty destination.
GitHub Actions logs, the image manifest, provenance attestation, and GitHub release are the publication record. Runtime health, capacity, request failures, and backup freshness remain the deployment operator's responsibility.
Roll back a deployment
Stop writes, redeploy the previously recorded digest, and restore the pre-rollout database only if the release changed persisted state incompatibly. Decide whether to restore data from the release notes and an approved migration plan; neither the container health check nor automation can infer database compatibility or an acceptable recovery point.
If PostgreSQL has accepted authoritative writes, do not switch back to the previous SQLite database: Drift does not provide reverse migration. Follow the PostgreSQL rollback guidance and identify the authoritative dataset before reopening writes.
Do not move or delete the published Git tag. If an image itself must be superseded, publish a new reviewed version and update consumers deliberately.