Implementation:MaterializeInc Materialize Cut Release Console

Knowledge Sources	misc/python/materialize/release/cut_release.py (lines 55-103)
Domains	Release Engineering, Docker, Git, Cross-Repository Coordination
Last Updated	2026-02-08

Overview

Concrete console repository tagging and DockerHub polling logic provided by the cut_release module in Materialize's release tooling.

Description

This section of cut_release.py (lines 62-103) performs the cross-repository coordination needed to ensure the console Docker image is available before the main Materialize release proceeds. The logic executes the following steps:

1. Clone the console repo from https://github.com/MaterializeInc/console into MZ_ROOT/console. If the directory already exists, it is removed first via shutil.rmtree(). HTTPS cloning is attempted first (with GIT_TERMINAL_PROMPT=0); if it fails, SSH cloning is used as a fallback.
2. Create and push the version tag on the console repo. The script first checks if the tag already exists (git tag -l version) to ensure idempotency. If not present, it creates an annotated tag and pushes it to origin.
3. Poll DockerHub for the console image. The script enters a while True loop that runs docker manifest inspect materialize/console:{version}. On failure (CalledProcessError), it sleeps 60 seconds and retries. On success, the loop breaks.

Usage

Use this implementation reference when debugging console release synchronization failures, understanding the DockerHub polling mechanism, or modifying how Materialize coordinates with the console repository during releases.

Code Reference

Source Location

misc/python/materialize/release/cut_release.py, lines 62-103.

Signature

# Within main(), after checkout(args.sha):
print("Cloning console repo")
console_dir = MZ_ROOT / "console"
if os.path.exists(console_dir):
    shutil.rmtree(console_dir)
try:
    spawn.runv(
        ["git", "clone", "https://github.com/MaterializeInc/console", console_dir],
        env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
    )
except subprocess.CalledProcessError:
    spawn.runv(
        ["git", "clone", "git@github.com:MaterializeInc/console", console_dir],
        env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
    )

print(f"Bumping console version to {version}")
existing_tag = spawn.capture(["git", "tag", "-l", version], cwd=console_dir)
if not existing_tag:
    spawn.runv(["git", "tag", "-a", version, "-m", version], cwd=console_dir)
    spawn.runv(["git", "push", "origin", version], cwd=console_dir)

print("Waiting for console version to be released on DockerHub (~15 min)")
console_version = version[1:]
console_image = f"materialize/console:{console_version}"
while True:
    try:
        spawn.capture(["docker", "manifest", "inspect", console_image])
    except subprocess.CalledProcessError:
        print(f"{console_image} not yet on DockerHub, sleeping 1 min")
        time.sleep(60)
        continue
    break
print(f"{console_image} found on DockerHub")

Import

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), derived from args.version
MZ_ROOT	pathlib.Path	Root of the Materialize repository, used to determine console clone location
Docker daemon	External service	Must be running for docker manifest inspect polling
GitHub access	External service	Must have read/write access to MaterializeInc/console

Outputs

Output	Type	Description
Console git tag	Side effect	An annotated tag matching the release version is created and pushed on the console repo
DockerHub image confirmation	Side effect	The function blocks until materialize/console:{version} is available on DockerHub
console_image	str	The fully qualified Docker image reference (e.g., materialize/console:0.79.0)
console_version	str	The version string without the v prefix (e.g., 0.79.0)

Usage Examples

Typical release invocation (console steps execute automatically):

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

Expected console output during execution:

Cloning console repo
Bumping console version to v0.79.0
Waiting for console version to be released on DockerHub (~15 min)
materialize/console:0.79.0 not yet on DockerHub, sleeping 1 min
materialize/console:0.79.0 not yet on DockerHub, sleeping 1 min
...
materialize/console:0.79.0 found on DockerHub

Checking if the console tag already exists (idempotent):

from materialize import spawn
existing_tag = spawn.capture(["git", "tag", "-l", "v0.79.0"], cwd=console_dir)
if not existing_tag:
    # Tag does not exist, create it
    spawn.runv(["git", "tag", "-a", "v0.79.0", "-m", "v0.79.0"], cwd=console_dir)

Related Pages

Implements Principle

• Principle:MaterializeInc_Materialize_Console_Release_Coordination