Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

6.0 KB
Raw Blame
#!/usr/bin/env python3
"""Bind release execution to a reviewed snapshot, independently of a moving train."""
from __future__ import annotations

import argparse
import json
import os
from pathlib import Path
import re
import subprocess


SHA = re.compile(r"[0-9a-f]{40}")
SNAPSHOT_REF = re.compile(r"release-candidate/[0-9A-Za-z._-]+")
# Post-merge dispatch refs. Only the release dispatcher can create or move
# them, so the release environment can admit them while unmerged
# release-candidate heads stay outside it. Each mirrors its PR's head name.
DISPATCH_REF = re.compile(r"release-dispatch/([0-9A-Za-z._-]+)")
SOURCE_BRANCH = re.compile(r"main|release/v[0-9]+\.[0-9]+(?:\.[1-9][0-9]*)?")


def snapshot_head(branch: str) -> str:
    """Return the PR head branch a snapshot dispatch branch must identify."""
    dispatch = DISPATCH_REF.fullmatch(branch)
    if dispatch:
        return "release-candidate/" + dispatch.group(1)
    if SNAPSHOT_REF.fullmatch(branch):
        return branch
    raise ValueError("release dispatch is not a reserved snapshot ref")


def source_branch(ref: str, requested: str, pull_request: str) -> str:
    if not ref.startswith("refs/heads/"):
        raise ValueError("release dispatch must name a branch ref")
    branch = ref.removeprefix("refs/heads/")
    if SNAPSHOT_REF.fullmatch(branch) or DISPATCH_REF.fullmatch(branch):
        if not SOURCE_BRANCH.fullmatch(requested) or not re.fullmatch(r"[1-9][0-9]*", pull_request):
            raise ValueError("snapshot dispatch requires its governed source branch and merged pull request")
        return requested
    if requested or pull_request:
        raise ValueError("snapshot provenance inputs require a reserved release-candidate or release-dispatch ref")
    if not SOURCE_BRANCH.fullmatch(branch):
        raise ValueError("release dispatch is outside a governed source branch")
    patch = re.fullmatch(r"release/v(\d+)\.(\d+)\.([1-9]\d*)", branch)
    if patch and tuple(map(int, patch.groups())) >= (6, 5, 1):
        # A new patch target is not protected main. Its execution must identify
        # the reviewed immutable preparation, not just a caller-controlled ref.
        raise ValueError("mechanical patches require a reviewed immutable snapshot")
    return branch


def reviewed_merge(pr: dict, *, repository: str, ref: str, branch: str, sha: str) -> str:
    if not SHA.fullmatch(sha):
        raise ValueError("source must be an exact commit")
    head, base = pr.get("head", {}), pr.get("base", {})
    if pr.get("merged") is not True or pr.get("state") != "closed":
        raise ValueError("release snapshot pull request is not merged")
    if head.get("sha") != sha or head.get("ref") != snapshot_head(ref.removeprefix("refs/heads/")):
        raise ValueError("pull request does not identify the dispatched snapshot")
    if base.get("ref") != branch:
        raise ValueError("pull request belongs to another release line")
    if any(part.get("repo", {}).get("full_name") != repository for part in (head, base)):
        raise ValueError("release snapshot must come from the canonical repository")
    merge = pr.get("merge_commit_sha", "")
    if not isinstance(merge, str) or not SHA.fullmatch(merge):
        raise ValueError("pull request has no exact merge commit")
    return merge


def check_workflow(path: Path) -> None:
    # BaseLoader preserves the YAML `on` key rather than treating it as a bool.
    import yaml

    workflow = yaml.load(path.read_text(), Loader=yaml.BaseLoader)
    inputs = workflow["on"]["workflow_dispatch"]["inputs"]
    for name in ("expected_source_sha", "release_source_branch", "release_pull_request"):
        if inputs.get(name, {}).get("type") != "string":
            raise ValueError(f"release workflow lacks snapshot input {name}")
    steps = workflow["jobs"]["prepare"]["steps"]
    guard = next((step for step in steps if step.get("id") == "snapshot"), {})
    if "python3 scripts/release_control/release_snapshot.py" not in guard.get("run", ""):
        raise ValueError("release workflow does not execute the snapshot provenance guard")
    expected = {"RELEASE_SOURCE_BRANCH": "${{ inputs.release_source_branch }}", "RELEASE_PULL_REQUEST": "${{ inputs.release_pull_request }}"}
    if any(guard.get("env", {}).get(key) != value for key, value in expected.items()):
        raise ValueError("release workflow does not bind snapshot provenance inputs")


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--check-workflow", type=Path)
    args = parser.parse_args()
    if args.check_workflow:
        check_workflow(args.check_workflow)
        return

    ref = os.environ["GITHUB_REF"]
    requested = os.environ.get("RELEASE_SOURCE_BRANCH", "")
    pr_number = os.environ.get("RELEASE_PULL_REQUEST", "")
    branch = source_branch(ref, requested, pr_number)
    if requested:
        repository = os.environ["GITHUB_REPOSITORY"]
        if repository != "rcourtman/Pulse":
            raise ValueError("snapshot releases are restricted to the canonical Pulse repository")
        sha = os.environ["GITHUB_SHA"]
        if os.environ["GITHUB_WORKFLOW_SHA"] != sha:
            raise ValueError("workflow and source must be the same immutable snapshot")
        pr = json.loads(subprocess.check_output(["gh", "api", f"repos/{repository}/pulls/{pr_number}"], text=True))
        merge = reviewed_merge(pr, repository=repository, ref=ref, branch=branch, sha=sha)
        subprocess.run(["git", "fetch", "--quiet", "--no-tags", f"https://github.com/{repository}.git", f"refs/heads/{branch}"], check=True)
        # Later merges are allowed. A rewrite that removes the reviewed merge is not.
        subprocess.run(["git", "merge-base", "--is-ancestor", sha, merge], check=True)
        subprocess.run(["git", "merge-base", "--is-ancestor", merge, "FETCH_HEAD"], check=True)
    with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output:
        output.write(f"source_branch={branch}\n")
    print(f"Release source is bound to {os.environ['GITHUB_SHA']} from {branch}")


if __name__ == "__main__":
    main()