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).
How a component releases
Section titled “How a component releases”Each component repository runs release-please
on its own (opentremor#0007). You do not tag a component by hand:
- Merge work into
mainusing Conventional Commit messages. - The repository’s
.github/workflows/release-please.ymlkeeps one Release PR up to date. It uses commit prefixes to choose the next version and updates the changelog and version manifest. - While the PR is open, the release has not happened. Review it as the release proposal.
- 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.
What the workflow needs to open the PR
Section titled “What the workflow needs to open the PR”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.
Where the release runs
Section titled “Where the release runs”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.
Commit prefixes
Section titled “Commit prefixes”| Prefix | Effect on the version | Changelog section |
|---|---|---|
fix: | Patch — 1.0.0 → 1.0.1 | Bug Fixes |
feat: | Minor — 1.0.0 → 1.1.0 | Features |
feat!:, or a BREAKING CHANGE: footer | Major — 1.0.0 → 2.0.0 | Breaking |
perf:, refactor:, deps:, build:, ci:, docs: | No version change on their own | Their own section |
test:, chore: | No version change | Hidden |
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.
Cut a workspace release
Section titled “Cut a workspace release”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:
./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.yamlgit commit -am "chore: release 1.2.0"git tag v1.2.0 && git push origin main v1.2.0The v* tag triggers the workspace release workflow. You can also run that workflow manually and provide a tag without the leading v.
What a workspace release publishes
Section titled “What a workspace release publishes”.github/workflows/release-images.yml runs for a v* tag or manually with a tag as input:
- Bootstrap — clones the component repositories at the refs pinned in
workspace.yaml. - Build and scan —
scripts/ci/build-images.shbuilds five images. The workflow scans them for fixable high and critical vulnerabilities. - Smoke test —
scripts/ci/chart-smoke.shinstalls 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. - End-to-end test — runs the suite against those images. If any check fails, the workflow stops before pushing.
- Publish — pushes and signs the five images, attaches SBOM attestations, and publishes and signs the Helm chart as an OCI artifact.
| Artifact | Location |
|---|---|
| Core (bundles platform and thirteen first-party packs) | ghcr.io/opentremor/opentremor-core:<version> |
| Dashboard | ghcr.io/opentremor/opentremor-dashboard:<version> |
| Docs | ghcr.io/opentremor/opentremor-docs:<version> |
| Task scheduler | ghcr.io/opentremor/opentremor-task-scheduler:<version> |
| Platform MCP | ghcr.io/opentremor/opentremor-mcp:<version> |
| Helm chart | oci://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:
scripts/ci/build-images.sh local.test 0.0.0scripts/ci/chart-smoke.sh local.test 0.0.0Deploy a release
Section titled “Deploy a release”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:
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.0The 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.
Registry access
Section titled “Registry access”The GHCR packages are private by default. A cluster needs a pull secret to fetch them:
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.