Implementation:MaterializeInc Materialize Cut Release Tag

Knowledge Sources	misc/python/materialize/release/cut_release.py (lines 127-141), misc/python/materialize/git.py
Domains	Release Engineering, Git, Version Control, Python
Last Updated	2026-02-08

Overview

Concrete release commit creation and annotated tag push logic provided by the cut_release module, using materialize.git.tag_annotated() for tag creation.

Description

This section of cut_release.py (lines 127-141) performs the final release operations after all version bumps and deployment configuration updates are complete:

1. Update deployment manifests: Rewrites misc/helm-charts/operator/templates/deployment.yaml to set the console image tag default using re.sub().
2. Commit all changes: Executes git commit -am "release: bump to version {version}" via spawn.runv(). The -a flag ensures all tracked, modified files are included.
3. Create annotated tag: Calls tag_annotated(version) from materialize.git, which runs git tag -a -m {tag} {tag}.
4. Push the tag: Pushes only the tag to the specified remote via git push {remote} {version}.

The tag_annotated() function from materialize.git is a thin wrapper:

def tag_annotated(tag: str) -> None:
    """Create an annotated tag on HEAD"""
    spawn.runv(["git", "tag", "-a", "-m", tag, tag])

All of this executes within the try/finally block that guarantees the original branch is restored when the release process completes (or fails).

Usage

Use this reference when understanding the final steps of the Materialize release process, debugging tag push failures, or modifying the commit message format for releases.

Code Reference

Source Location

misc/python/materialize/release/cut_release.py, lines 127-141.

Supporting function: misc/python/materialize/git.py, tag_annotated().

Signature

# Within main(), after version bumping and Dockerfile update:
deployment = pathlib.Path("misc/helm-charts/operator/templates/deployment.yaml")
deployment_text = deployment.read_text()
deployment.write_text(
    re.sub(
        r'"--console-image-tag-default=[^"]*"',
        f'"--console-image-tag-default={console_version}"',
        deployment_text,
    )
)
# Commit here instead of in bump-version so we have access to the correct git author
spawn.runv(["git", "commit", "-am", f"release: bump to version {version}"])
print("Tagging version")
tag_annotated(version)
print("Pushing tag to Materialize repo")
spawn.runv(["git", "push", args.remote, version])

Import

The tag_annotated function is imported in cut_release.py as:

from materialize.git import checkout, get_branch_name, tag_annotated

The overall release module:

from materialize.release.cut_release import main

I/O Contract

Inputs

Input	Type	Description
version	str	The version string with v prefix (e.g., v0.79.0)
console_version	str	The version string without v prefix (e.g., 0.79.0), used for Helm deployment template
args.remote	str	The git remote name to push the tag to (e.g., origin)
Modified working tree	Precondition	All version bumps and Dockerfile updates must be complete before this step

Outputs

Output	Type	Description
Git commit	Side effect	A single commit with message "release: bump to version {version}" containing all version changes
Annotated git tag	Side effect	An annotated tag named {version} (e.g., v0.79.0) pointing to the release commit
Pushed tag	Side effect	The annotated tag is pushed to the specified remote repository

Usage Examples

Full release invocation (tagging happens automatically):

python -m materialize.release.cut_release \
    --sha abc123def456 \
    --version v0.79.0 \
    --remote origin

Expected output during the tagging phase:

Bumping version to v0.79.0
[... version bump output ...]
Tagging version
Pushing tag to Materialize repo

Using tag_annotated directly:

from materialize.git import tag_annotated

# Create an annotated tag on the current HEAD
tag_annotated("v0.79.0")
# Equivalent to: git tag -a -m v0.79.0 v0.79.0

Verifying the annotated tag after creation:

# Show tag details (tagger, date, message)
git show v0.79.0

# List only annotated tags
git for-each-ref refs/tags --format='%(objecttype) %(refname:short)' | grep '^tag '

Related Pages

Implements Principle

• Principle:MaterializeInc_Materialize_Release_Commit_and_Tagging