Skip to content

Release Process

flowchart LR
  tag[Git tag vX.Y.Z] --> ci[CI tests]
  ci --> build[build-release.ps1]
  build --> art[4 platform artifacts]
  art --> sha[SHA256SUMS]
  sha --> man[release-manifest.json]
  man --> val[validate-release.ps1]
  val --> gh[GitHub Release]
  gh --> dep[Manual customer deploy]
  1. Stabilize on release/vX.Y.Z.
  2. Merge to main.
  3. Tag vX.Y.Z on the intended commit.
  4. .github/workflows/release.yml builds, validates, and publishes the GitHub Release.
  5. Customer deployment is a manual operational step from the downloaded archive.

One application version = one GitHub Release. All four platform archives share that version and commit.

Release assets (v1.0.0 example)

text iqv-integration-api-v1.0.0-windows-native-amd64.zip iqv-integration-api-v1.0.0-windows-docker-amd64.zip iqv-integration-api-v1.0.0-linux-native-amd64.tar.gz iqv-integration-api-v1.0.0-linux-docker-amd64.tar.gz SHA256SUMS release-manifest.json

Asset Platform What it actually contains
*-windows-native-amd64.zip Windows Native Source tree + existing scripts/windows/service installer. Host still needs Go and Git. Not a prebuilt .exe.
*-windows-docker-amd64.zip Windows Docker Source + Dockerfile/compose + existing installer. Host still runs docker build. Docker Desktop Linux containers. Extracted zip uses release-package mode (manifest provenance; no .git / clone). Not an offline docker load image.
*-linux-native-amd64.tar.gz Linux Native Offline prebuilt binary + scripts/install.sh. No Go/Git on the customer host.
*-linux-docker-amd64.tar.gz Linux Docker Offline prebuilt OCI image/*.tar + compose + install/update. No docker build on the customer host.

Inner Linux packager names (iqv-integration-api-<version>-linux-amd64.tar.gz without the extra v / -native- segment) remain the existing builder output. The orchestrator copies them to the GitHub Release names above.

Version and commit

  • Tag is the production source of truth (v1.0.0, v1.0.0-rc.1).
  • release-manifest.json version must equal the tag.
  • release-manifest.json commit is the full Git SHA of that tag.
  • Artifact filenames must contain the same version string.
  • Stable vX.Y.Z builds fail closed on a dirty worktree. -AllowDirty is rejected for stable versions.

Local production candidate (clean tree)

After the release commit is clean:

powershell .\scripts\release\build-release.ps1 -Version v1.0.0 .\scripts\release\validate-release.ps1 -Version v1.0.0 -RequireClean

Lab / dirty tree (not for v1.0.0):

powershell .\scripts\release\build-release.ps1 -Version v0.0.0-testdev -AllowDirty -SkipGitChecks -Commit <full-sha> -SkipQuality -SkipDocs

Download from GitHub Releases

  1. Open the repository Releases page and select the tag (example v1.0.0).
  2. Download the archive for your platform and SHA256SUMS + release-manifest.json.
  3. Verify checksums before extract/install.

SHA256 verification

Linux:

bash sha256sum -c SHA256SUMS

Windows (PowerShell):

powershell Get-Content .\SHA256SUMS | ForEach-Object { if ($_ -match '^([0-9a-fA-F]{64}) (.+)$') { $actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $Matches[2]).Hash.ToLower() if ($actual -ne $Matches[1].ToLower()) { throw "Mismatch $($Matches[2])" } } }

Manifest verification

release-manifest.json lists all four artifacts with platform, deployment, arch, file, and sha256. The sha256 values must match both the files on disk and SHA256SUMS. scripts/release/validate-release.ps1 performs that check plus archive content and secret scans.

Install after download

  • Windows Native: extract the zip, copy .env.example → .env, run scripts\windows\service\install.ps1. See Windows Native.
  • Windows Docker: extract the zip, copy .env.example → env file, run .\scripts\install.ps1 with Docker Desktop Linux containers and external MongoDB (host.docker.internal when MongoDB is on the host). No .git and no clone required (release-package mode). See Windows Docker.
  • Linux Native: extract the tar.gz, run sudo ./scripts/install.sh. See Linux Native.
  • Linux Docker: extract the tar.gz, run sudo ./scripts/install.sh (loads image/*.tar). See Linux Docker.

GitHub Actions

.github/workflows/release.yml:

  • Triggers: push of v*.*.* tags, or workflow_dispatch with an existing tag.
  • Checks out that exact tag, runs tests/docs via build-release.ps1, then validate-release.ps1.
  • Creates or updates the GitHub Release and uploads the six assets (--clobber on rerun).
  • v1.0.0 is a stable release. v1.0.0-rc.1 is published as a prerelease.

The workflow does not create tags. Operators tag locally and push the tag.

Acceptance checklist

Use Release Acceptance Checklist before tagging.

Current documented version metadata: docs/site-meta.yml (stays unreleased until a version is actually published).

To align docs with a tag without inventing a publish:

powershell python scripts/docs/apply_docs_version.py --version v1.0.0 --check # fails while still unreleased python scripts/docs/apply_docs_version.py --version v1.0.0 --write # operator: run on the release commit before tag

Release CI may set IQV_RELEASE_ALIGN_DOCS=1 for an ephemeral workspace docs build after packaging. Landing page assembly also accepts IQV_DOCS_VERSION.