Skip to content
DashboardWebsite

Releasing

A component release versions one repository. A workspace release tags the root opentremor repository to identify the component refs released together, then builds and checks the deployable images (opentremor#0001, opentremor#0018).

Each component repository runs release-please on its own (opentremor#0007). You do not tag a component by hand:

  1. Merge work into main using Conventional Commit messages.
  2. The repository’s .github/workflows/release-please.yml keeps one Release PR up to date. It uses commit prefixes to choose the next version and updates the changelog and version manifest.
  3. While the PR is open, the release has not happened. Review it as the release proposal.
  4. Merging the Release PR is the release. release-please tags the merge commit and creates a GitHub Release with the changelog. A component tag does not publish an image.

The workflow uses the WORKSPACE_TOKEN secret when it is set, and falls back to GITHUB_TOKEN otherwise. For GITHUB_TOKEN to open the Release PR, enable Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests in the repository or organization.

A PR opened with GITHUB_TOKEN does not trigger other workflow runs. Use WORKSPACE_TOKEN when the Release PR needs CI.

The release-please jobs run on self-hosted runners (runs-on: self-hosted), like the component CI jobs. If no matching runner is available, the job waits for one.

PrefixEffect on the versionChangelog section
fix:Patch — 1.0.0 → 1.0.1Bug Fixes
feat:Minor — 1.0.0 → 1.1.0Features
feat!:, or a BREAKING CHANGE: footerMajor — 1.0.0 → 2.0.0Breaking
perf:, refactor:, deps:, build:, ci:, docs:No version change on their ownTheir own section
test:, chore:No version changeHidden

A series of docs:-only commits does not create a new version. The version changes when a commit type configured to release a version lands.

Scopes are optional and free-form. For example, feat(core): … and fix(dashboard): … include the scope in the changelog entry.

workspace.yaml lists the component repositories and the refs that make up the workspace. Update the refs for the components you want to include, then pin the manifest to the checked-out refs:

Terminal window
./bootstrap.sh # clone components at their pinned refs
# Check out the release tags for the components you want to include, then:
./bootstrap.sh --pin # write the checked-out refs to workspace.yaml
git commit -am "chore: release 1.2.0"
git tag v1.2.0 && git push origin main v1.2.0

The v* tag triggers the workspace release workflow. You can also run that workflow manually and provide a tag without the leading v.

.github/workflows/release-images.yml runs for a v* tag or manually with a tag as input:

  1. Bootstrap — clones the component repositories at the refs pinned in workspace.yaml.
  2. Build and scan — scripts/ci/build-images.sh builds five images. The workflow scans them for fixable high and critical vulnerabilities.
  3. Smoke test — scripts/ci/chart-smoke.sh installs the chart into a temporary kind cluster with all chart workloads enabled and bundled MongoDB. It waits for workloads to become ready and checks core’s /health/ready.
  4. End-to-end test — runs the suite against those images. If any check fails, the workflow stops before pushing.
  5. Publish — pushes and signs the five images, attaches SBOM attestations, and publishes and signs the Helm chart as an OCI artifact.
ArtifactLocation
Core (bundles platform and thirteen first-party packs)ghcr.io/opentremor/opentremor-core:<version>
Dashboardghcr.io/opentremor/opentremor-dashboard:<version>
Docsghcr.io/opentremor/opentremor-docs:<version>
Task schedulerghcr.io/opentremor/opentremor-task-scheduler:<version>
Platform MCPghcr.io/opentremor/opentremor-mcp:<version>
Helm chartoci://ghcr.io/opentremor/charts/opentremor:<version>

The image and chart version omits the leading v from the workspace tag.

You can run the image build and chart smoke test locally from the workspace root with Docker, kind, kubectl, and Helm:

Terminal window
scripts/ci/build-images.sh local.test 0.0.0
scripts/ci/chart-smoke.sh local.test 0.0.0

The Helm chart is published as an OCI artifact. Install it with the workspace release version and set each enabled workload’s image tag to match:

Terminal window
helm install opentremor oci://ghcr.io/opentremor/charts/opentremor \
--version 1.2.0 \
--set config.auth.apiKey="$(openssl rand -base64 32)" \
--set mongodb.enabled=true \
--set image.tag=1.2.0 \
--set dashboard.enabled=true --set dashboard.image.tag=1.2.0 \
--set docs.enabled=true --set docs.image.tag=1.2.0 \
--set taskScheduler.enabled=true --set taskScheduler.image.tag=1.2.0 \
--set mcp.enabled=true --set mcp.image.tag=1.2.0

The chart’s default image tags follow the chart’s own version. Set the tags to the workspace release version as shown.

The published dashboard and docs images use the chart’s path-prefixed ingress setup: dashboard at /dashboard, docs at /docs, with same-origin API calls. Next.js and the docs base path are configured at build time. If you use different paths or origins, build images with matching settings.

The GHCR packages are private by default. A cluster needs a pull secret to fetch them:

Terminal window
kubectl create secret docker-registry ghcr-pull-secret \
--namespace opentremor \
--docker-server=ghcr.io \
--docker-username=<github-username> \
--docker-password=<PAT with read:packages>

The values-dev.yaml and values-prod.yaml profiles reference this secret by name.