This repository has been archived on 2026-11-08. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
platform-ci/platform_ci/delivery/finalize_version.py

294 lines
19 KiB
Python

"""The trusted version write-back command (`finalize-version`): persist the VERIFIED, PUBLISHED effective version to the source, in pinned platform code only.
The isolated callback wiring is not deployed or tested. Direct push invocation remains supported; the explicit
--original-run route authenticates a distinct canonical workflow_dispatch against the completed original push.
It never checks out, builds or runs the source, never rebuilds, and invents no version. It consumes what already exists:
* the repository's own `.ci.yaml` at the release commit, read through the forge: a channel that matches the pushed branch or tag AND declares `version_write_back` is the only opt-in;
* the VERIFIED bundle of the release run, selected by the publisher's own `select_artifacts` (same run, attempt, tree, manifest, config and platform identity proofs, same recomputed build
inputs including the effective version), so the version written is exactly the `build_inputs.version` the bundle recorded;
* the publication evidence the trusted publisher already wrote: the Maven files read back byte-identical from the private registry and, where the channel asks for Central completion, the
terminal completion receipt of exactly this reactor (`source_lifecycle.postpublish`); an absent one is `NotYetPublished`, nothing is written, and a later invocation retries.
The write itself is `source_lifecycle`: a staging branch, one server-signed `PUT` of the root POM's `<revision>`, strict re-verification, a normal non-forced fast-forward push. The credential is
the job's own ephemeral token (`FORGE_TOKEN`), exactly as the existing `release-tag` phase; this module reads no secret, creates no credential and grants nothing.
"""
import json
import tempfile
import urllib.request
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Final, cast, override
from platform_ci.configuration import ProjectConfiguration, ReleaseChannel, WriteBackPolicy, parse_project_configuration_text, parse_yaml_rejecting_duplicate_keys
from platform_ci.delivery import legacy
from platform_ci.delivery.adapters import selected_artifact_files
from platform_ci.delivery.errors import DeliveryError
from platform_ci.delivery.forge import ClientForge, CurrentRun, ForgeReader, RepositoryScope, current_workflow_trust, inspect_run, read_file, require_repository
from platform_ci.delivery.manifest import ManifestFile
from platform_ci.delivery.promotion import REUSE_MAX_ARTIFACT_BYTES, REUSE_RUNS_SCANNED
from platform_ci.delivery.publisher import RunInProgressError, select_artifacts
from platform_ci.delivery.release_tag import CONFIGURATION_PATH, TRUSTED_FORGE
from platform_ci.delivery.reuse import ReleaseArtifact
from platform_ci.delivery.reuse_forge import live_reuse_forge
from platform_ci.delivery.source_lifecycle import Fatal, NotYetPublished, SourceWriter, VersionGit, WriteContext, postpublish
from platform_ci.event_selection import EventFacts, channel_matches, push_facts, tag_facts
from platform_ci.plan import publication_requests
from platform_ci.runtimes import RuntimeCatalog, load_runtime_catalog
_BRANCH_PREFIX: Final = "refs/heads/"
_TAG_PREFIX: Final = "refs/tags/"
_COMMIT_LENGTH: Final = 40
MAVEN_FORMAT: Final = "maven"
_CANONICAL_PLATFORM_REPOSITORY_ID: Final = 3
_PUBLIC_METADATA_LIMIT: Final = 2_000_000
@dataclass(frozen=True)
class _Request:
"""The validated facts the workflow supplies: the pushed ref, the release commit, the repository and run identity, the token and the optional release run."""
ref: str
sha: str
branch: str
tag: str
repository: str
repository_id: int
run_id: int
attempt: int
platform: str
token: str
release_run: int | None
source_id: int
def _read_request(environment: Mapping[str, str]) -> _Request:
"""Validate the environment of a write-back; any missing or malformed fact is an error before a single read is made."""
if environment.get("CI_EVENT_NAME") != "push":
raise DeliveryError("a version write-back runs only for the push of a release branch or tag")
ref, sha = environment.get("CI_EVENT_REF", ""), environment.get("CI_SOURCE_REVISION", "")
branch, tag = ref.removeprefix(_BRANCH_PREFIX) if ref.startswith(_BRANCH_PREFIX) else "", ref.removeprefix(_TAG_PREFIX) if ref.startswith(_TAG_PREFIX) else ""
repository, repository_id = environment.get("CI_REPOSITORY", ""), environment.get("CI_REPOSITORY_ID", "")
run_id, attempt, platform = environment.get("CI_RUN_ID", ""), environment.get("CI_RUN_ATTEMPT", ""), environment.get("CI_PLATFORM_REVISION", "")
if not (bool(branch) ^ bool(tag)) or len(sha) != _COMMIT_LENGTH or not repository or not repository_id.isdigit() or not run_id.isdigit() or not attempt.isdigit() or len(platform) != _COMMIT_LENGTH:
raise DeliveryError("the pushed branch or tag, the release commit, the platform revision and the repository and run identity are required")
if environment.get("GITHUB_SERVER_URL", "").rstrip("/") != TRUSTED_FORGE:
raise DeliveryError("the runner's forge is not the trusted private forge")
token = environment.get("FORGE_TOKEN", "")
if not token:
raise DeliveryError("the job's own token is required")
release_run = environment.get("CI_RELEASE_RUN_ID", "")
if release_run and not release_run.isdigit():
raise DeliveryError("CI_RELEASE_RUN_ID must be a run number")
source_id = environment.get("CI_SCOPED_SOURCE_ID", "0")
if not source_id.isdigit():
raise DeliveryError("CI_SCOPED_SOURCE_ID must be a number")
return _Request(ref, sha, branch, tag, repository, int(repository_id), int(run_id), int(attempt), platform, token, int(release_run) if release_run else None, int(source_id))
def finalize_version( # noqa: PLR0913, PLR0917 - the injected clients replace the live ones only for tests
environment: Mapping[str, str],
forge: ForgeReader | None = None,
writer: Callable[..., tuple[int, Any]] | None = None,
git: VersionGit | None = None,
registry_reader: Callable[..., tuple[int, bytes]] | None = None,
completion_reader: Callable[..., tuple[int, bytes]] | None = None,
runtimes: RuntimeCatalog | None = None,
*,
original_run: int | None = None,
) -> list[str]:
"""Write back the version of the release identified by the environment; return one line describing the outcome. Any doubt is an error, never a skip.
Required environment (all set by the workflow, none by the source): the event name `push`, the pushed ref (`refs/heads/<branch>` or `refs/tags/<tag>`), the exact release commit, the repository
and run identity, this run's attempt, the canonical source id and workflow sha, the platform revision, and the job's token. Optional `CI_RELEASE_RUN_ID` names the release run to consume
(otherwise the publisher's own run selection applies). Injected clients replace the live ones only for tests.
"""
if original_run is None:
request = _read_request(environment)
client = forge
trusted_original = None
else:
request, client, trusted_original = _callback_request(environment, original_run, forge)
sha, branch, tag = request.sha, request.branch, request.tag
scope = RepositoryScope(request.repository, request.repository_id, REUSE_MAX_ARTIFACT_BYTES, REUSE_RUNS_SCANNED, frozenset({request.platform}))
client = client or live_reuse_forge(request.token, scope)
require_repository(client, scope)
trusted = trusted_original or current_workflow_trust(client, scope, CurrentRun(request.run_id, sha, request.source_id, environment.get("CI_WORKFLOW_SHA", "")))
if trusted is None:
raise DeliveryError("the forge does not prove this run was executed by the canonical workflow, so no release run can be trusted")
content = read_file(client, request.repository, CONFIGURATION_PATH, sha)
if content is None:
return ["no .ci.yaml at the release commit: nothing to write back"]
project = parse_project_configuration_text(content.decode("utf-8"))
facts = push_facts(branch, sha) if branch else tag_facts(tag, sha)
channels = _write_back_channels(project, facts)
if not channels:
return [f"no channel matching {request.ref} declares version_write_back: nothing to write back"]
policy = _one_policy(channels)
target_branch = branch or policy.target_branch
planned = [publication for publication in publication_requests(project, [channel.name for channel in channels]) if publication["format"] == MAVEN_FORMAT]
if not planned:
raise DeliveryError("the channels that write a version back publish no Maven package at this commit, so there is no verified publication to wait for")
ctx = WriteContext(request.repository, sha, target_branch, request.run_id, request.attempt, tag)
owner = request.repository.split("/", 1)[0] # the enrolled owner always equals the repository's: `enrollment.py` rejects any other
with tempfile.TemporaryDirectory() as scratch:
try:
artifacts, _notes = select_artifacts(client, trusted, runtimes or load_runtime_catalog(), project, sha, facts, planned, request.release_run, Path(scratch))
except RunInProgressError as error:
raise NotYetPublished(str(error)) from error
evidence: list[tuple[ReleaseArtifact, tuple[ManifestFile, ...], str]] = []
for publication in planned:
artifact = artifacts[publication["target"]]
inputs = artifact.manifest.build_inputs
if inputs is None:
raise Fatal(f"the verified bundle of {publication['target']!r} records no build inputs, so no version can be written back")
evidence.append((artifact, selected_artifact_files(artifact, publication["artifact"]), inputs.version))
versions = {version for _, _, version in evidence}
if len(versions) != 1:
raise Fatal(f"the verified bundles record different versions {sorted(versions)}; one POM cannot carry them")
version = next(iter(versions))
first, *rest = evidence
result = postpublish(
ctx,
policy,
artifact=first[0],
files=first[1],
version=version,
owner=owner,
repository_id=request.repository_id,
central_required=any(channel.central_completion for channel in channels),
writer=writer or SourceWriter(request.token, ctx),
registry_reader=registry_reader or legacy.package_client(request.token, owner, "maven"),
completion_reader=completion_reader or legacy.package_client(request.token, owner, "generic"),
git=git or VersionGit(TRUSTED_FORGE, request.repository, request.token),
extra_evidence=tuple((artifact, files) for artifact, files, _ in rest),
)
detail = f" ({result['reason']})" if result["reason"] else ""
pushed = f" {result['pushed_sha'][:12]}" if result["pushed_sha"] else ""
return [f"version write-back of {version} to {target_branch}: {result['status']}{pushed}{detail}"]
def _write_back_channels(project: ProjectConfiguration, facts: EventFacts) -> list[ReleaseChannel]:
"""Return the channels this push matches that opted in to a version write-back."""
return [channel for channel in project.channels if channel.version_write_back is not None and channel_matches(channel, facts)]
def _one_policy(channels: list[ReleaseChannel]) -> WriteBackPolicy:
"""Return the single policy of the matching channels; two different ones would give two targets for one write and are an error."""
policies = {channel.version_write_back for channel in channels}
if len(policies) != 1:
raise DeliveryError(f"channels {sorted(channel.name for channel in channels)} declare different version_write_back policies for one event")
(policy,) = policies
if policy is None:
raise DeliveryError("a channel selected for a version write-back declares no version_write_back policy")
return policy
def _callback_request(environment: Mapping[str, str], original_run: int, forge: ForgeReader | None) -> tuple[_Request, ForgeReader, RepositoryScope]:
"""Authenticate the callback and original push separately. Never substitute a push event in the callback environment."""
if environment.get("CI_EVENT_NAME") != "workflow_dispatch" or original_run <= 0:
raise DeliveryError("an original-run callback requires a workflow_dispatch and a positive original run id")
# Validate common runner facts without pretending this dispatch is a source push.
ref = environment.get("CI_EVENT_REF", "")
repository = environment.get("CI_REPOSITORY", "")
sha = environment.get("CI_SOURCE_REVISION", "")
ids = [environment.get(key, "") for key in ("CI_REPOSITORY_ID", "CI_RUN_ID", "CI_RUN_ATTEMPT", "CI_SCOPED_SOURCE_ID")]
platform, workflow = environment.get("CI_PLATFORM_REVISION", ""), environment.get("CI_WORKFLOW_SHA", "")
token = environment.get("FORGE_TOKEN", "")
if not all(value.isdigit() and int(value) > 0 for value in ids) or any(len(value) != _COMMIT_LENGTH or any(c not in "0123456789abcdef" for c in value) for value in (sha, platform, workflow)):
raise DeliveryError("callback repository/run/source identity and full platform/workflow/source revisions are required")
if not repository or not token or environment.get("GITHUB_SERVER_URL", "").rstrip("/") != TRUSTED_FORGE:
raise DeliveryError("the callback requires its own token and trusted forge/repository")
repository_id, callback_id, attempt, source_id = map(int, ids)
if callback_id == original_run:
raise DeliveryError("a callback cannot name itself as its original run")
scope = RepositoryScope(repository, repository_id, REUSE_MAX_ARTIFACT_BYTES, REUSE_RUNS_SCANNED, frozenset({platform}))
client = forge or live_reuse_forge(token, scope)
require_repository(client, scope)
callback = current_workflow_trust(client, scope, CurrentRun(callback_id, sha, source_id, workflow))
if callback is None or len(callback.scoped_workflows) != 1 or next(iter(callback.scoped_workflows)).workflow_file != "finalize-version.yaml":
raise DeliveryError("callback is not the pinned canonical scoped finalizer")
original_value = client.get(f"/repos/{repository}/actions/runs/{original_run}")
if not isinstance(original_value, dict):
raise DeliveryError("the original run is not a source push at this exact callback commit")
original = cast("dict[str, Any]", original_value)
if original.get("head_sha") != sha or original.get("event") != "push":
raise DeliveryError("the original run is not a source push at this exact callback commit")
original_ref = str(original.get("path", "")).partition("@")[2]
if original_ref != ref or not original_ref.startswith(("refs/heads/", "refs/tags/")):
raise DeliveryError("callback and original push refs differ or are not fully qualified")
trusted = current_workflow_trust(client, scope, CurrentRun(original_run, sha, source_id))
if trusted is None:
raise DeliveryError("the original push was not executed by the canonical workflow")
if platform != _canonical_build_revision(trusted):
raise DeliveryError("callback build helper differs from the original canonical pipeline's immutable build pin")
facts = inspect_run(client, trusted, original_run)
if facts.status != "completed" or facts.conclusion != "success" or facts.head_sha != sha or facts.event != "push":
raise DeliveryError("the exact original push and its required jobs must have completed successfully")
if facts.attempt != environment.get("CI_ORIGINAL_ATTEMPT"):
raise DeliveryError("the original push attempt changed after publication handoff")
branch = ref.removeprefix(_BRANCH_PREFIX) if ref.startswith(_BRANCH_PREFIX) else ""
tag = ref.removeprefix(_TAG_PREFIX) if ref.startswith(_TAG_PREFIX) else ""
# Staging names use THIS callback's run/attempt. Artifact selection deliberately remains default:
# the completed source push may reuse the earlier PR's verified bundles and have none of its own.
return _Request(ref, sha, branch, tag, repository, repository_id, callback_id, attempt, platform, token, None, source_id), client, trusted
class _NoCanonicalRedirect(urllib.request.HTTPRedirectHandler):
"""The public canonical workflow read never redirects or carries a credential."""
@override
def redirect_request(self, *args: object, **kwargs: object) -> None:
return None
def _canonical_build_revision(trusted: RepositoryScope) -> str:
"""Read the literal build pin from the pipeline YAML at the server-proven canonical workflow commit."""
if len(trusted.scoped_workflows) == 1:
workflow = next(iter(trusted.scoped_workflows))
revision = workflow.callee_workflow_sha
if not revision and workflow.source_repository_id == _CANONICAL_PLATFORM_REPOSITORY_ID and workflow.workflow_file == "pipeline.yaml":
revision = workflow.workflow_sha
elif len(trusted.workflow_references) == 1:
reference = next(iter(trusted.workflow_references))
prefix = "self:KofTwentyTwo/platform-ci/.gitea/scoped_workflows/pipeline.yaml@"
revision = reference.removeprefix(prefix) if reference.startswith(prefix) else ""
else:
revision = ""
if len(revision) != _COMMIT_LENGTH or any(char not in "0123456789abcdef" for char in revision):
raise DeliveryError("original run has no independently proved canonical pipeline commit")
repository = "KofTwentyTwo/platform-ci"
filename = ".gitea/scoped_workflows/pipeline.yaml"
expected_path = f"/repos/{repository}/contents/{filename}?ref={revision}"
opener = urllib.request.build_opener(_NoCanonicalRedirect())
def public_get(path: str) -> object:
if path != expected_path:
raise DeliveryError("canonical metadata reader refuses any other repository, file or revision")
# Only public platform code leaves/enters this request: no source SHA, source data or credential.
request = urllib.request.Request(TRUSTED_FORGE + "/api/v1" + expected_path, method="GET") # noqa: S310 - fixed trusted HTTPS origin, exact immutable path, no redirects
with opener.open(request, timeout=30) as response:
raw = response.read(_PUBLIC_METADATA_LIMIT + 1)
if len(raw) > _PUBLIC_METADATA_LIMIT:
raise DeliveryError("canonical pipeline metadata exceeds the existing file bound")
return cast("object", json.loads(raw))
def no_download(_path: str, _destination: Path, _limit: int) -> None:
raise DeliveryError("canonical workflow metadata reader downloads no artifact")
content = read_file(ClientForge(public_get, no_download), repository, filename, revision)
document = parse_yaml_rejecting_duplicate_keys(content.decode("utf-8")) if content is not None else None
if not isinstance(document, dict):
raise DeliveryError("canonical pipeline YAML is absent or malformed")
fields = cast("dict[str, Any]", document)
environment = fields.get("env")
if not isinstance(environment, dict):
raise DeliveryError("canonical pipeline has no literal build helper pin")
build = cast("dict[str, Any]", environment).get("PLATFORM_CI_REVISION")
if not isinstance(build, str) or len(build) != _COMMIT_LENGTH or any(char not in "0123456789abcdef" for char in build):
raise DeliveryError("canonical pipeline build helper pin is not an immutable commit")
return build