Workflow:MaterializeInc Materialize Release Process
| Knowledge Sources | |
|---|---|
| Domains | Release_Management, Version_Control, CI_CD |
| Last Updated | 2026-02-08 21:00 GMT |
Overview
End-to-end process for cutting a new Materialize release, including version bumping, console image coordination, Helm chart updates, and git tagging.
Description
This workflow describes the multi-step release process orchestrated by cut_release.py and supporting automation scripts. A release involves coordinating version bumps across the main Materialize repository and the console repository, waiting for Docker images to build and publish, updating Helm chart configurations, and creating annotated git tags. The process supports both regular releases and automated release cutting via auto_cut_release.py, which can be triggered on a schedule to start new minor version series.
Usage
Execute this workflow when a release manager needs to cut a new Materialize release. The workflow requires a specific git SHA to release from, a semantic version number, and access to push tags to the upstream repository. It is typically run after all CI checks pass on the target commit and after coordination with the release team.
Execution Steps
Step 1: Verify Prerequisites
Verify that Docker is running (required for console image operations), the target git SHA exists and is on an appropriate branch, and the release version follows semantic versioning conventions. The release script validates these preconditions before proceeding.
Key considerations:
- Docker must be running locally for console repository operations
- The target SHA should have passed all CI checks
- Version numbers follow the pattern v0.XX.Y (major.minor.patch)
- The release operator needs push access to the upstream git remote
Step 2: Coordinate Console Release
Clone the console repository, tag the console at the corresponding version, and push the tag to GitHub. This triggers the console CI pipeline to build and publish the console Docker image to DockerHub. The release script waits for the image to become available before proceeding.
Key considerations:
- The console repository is a separate git repository that must be coordinated
- The console image build and publish takes approximately 15 minutes
- The script polls DockerHub until the image is available
- Console version tags follow a coordinated naming scheme with the main repository
Step 3: Bump Version Numbers
Update the Materialize version across the repository. This involves modifying version files, Cargo.toml manifests, and other version-bearing files. The bin/bump-version script handles the mechanical version updates across all locations.
Key considerations:
- Version bumps must be consistent across Rust (Cargo.toml), Python, and documentation
- The version string appears in multiple files that must all be updated atomically
- The bump script handles the specific format and location requirements
- Both the release version and the next development version may need updates
Step 4: Update Deployment Configuration
Update the Dockerfile to reference the newly published console image tag. Update the Helm chart deployment configuration with the new console version. These changes ensure that deployments of this release use the correct console version.
Key considerations:
- The Dockerfile must reference the exact console image tag, not a floating tag
- Helm chart values must be updated for the operator deployment
- These changes are committed as part of the release commit
- The configuration must match the console version published in Step 2
Step 5: Create Release Commit and Tag
Create a git commit containing all version bumps and configuration updates. Create an annotated git tag at that commit with the release version. Push the tag to the upstream remote, which triggers the release CI pipeline to build and publish release artifacts.
Key considerations:
- The commit message follows a standard format for release commits
- The git author is set appropriately for the release commit
- The annotated tag triggers CI release workflows (binary builds, Docker image publishing)
- After tagging, the release branch may need a forward version bump for the next development cycle
Step 6: Mark Release Complete
After all release artifacts are published and validated, mark the release series as complete. This updates the version metadata to indicate the release is finalized and available for users. The mark_release_complete.py script handles this final step.
Key considerations:
- Release completion marks the version as available in the version list
- The version list is used by upgrade testing to determine test targets
- Completion should only happen after all artifacts are verified
- Failed releases need manual intervention to clean up tags and artifacts