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.

Avoid runtime CI fan-out for browser-receipt-only tree changes

pulse-triage[bot]a3fe70feb809
diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml
index f2f9b7a86f..83d4e8f72a 100644
--- a/.github/workflows/build-and-test.yml
+++ b/.github/workflows/build-and-test.yml
@@ -85,6 +85,9 @@ jobs:
- name: Check shipped docs before dependency work
run: python3 scripts/check_docs_mirror.py
+ - name: Validate browser receipt-only CI admission
+ run: python3 scripts/tests/test_ci_browser_proof_only.py
+
- name: Classify changed files
id: filter
run: |
@@ -101,6 +104,17 @@ jobs:
echo "go_compile=true" >> "$GITHUB_OUTPUT"
exit 0
fi
+ # Receipts change evidence, not the application. Keep the per-push
+ # secret scan and Canonical Governance (including receipt validation).
+ # The complete tree diff must be receipt-only; mixed source or graph
+ # changes and an unavailable diff never enter this path.
+ if [ "$(python3 scripts/ci_browser_proof_only.py --base "$base" --head "${{ github.sha }}")" = true ]; then
+ echo "Browser receipt-only tree diff; runtime checks are not applicable."
+ echo "code=false" >> "$GITHUB_OUTPUT"
+ echo "frontend_deps=false" >> "$GITHUB_OUTPUT"
+ echo "go_compile=false" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
changed=$(git diff --name-only "$base" "${{ github.sha }}")
printf 'Changed files:\n%s\n' "$changed"
# Note: -q must not be combined with -v here — BSD grep exits 1 for
diff --git a/.github/workflows/test-e2e.yml b/.github/workflows/test-e2e.yml
index dc865f1665..26f05ad6e0 100644
--- a/.github/workflows/test-e2e.yml
+++ b/.github/workflows/test-e2e.yml
@@ -18,6 +18,8 @@ on:
- 'scripts/tests/test_e2e_test_images.py'
- 'scripts/collect_e2e_container_logs.py'
- 'scripts/tests/test_e2e_container_logs.py'
+ - 'scripts/ci_browser_proof_only.py'
+ - 'scripts/tests/test_ci_browser_proof_only.py'
push:
branches:
- main
@@ -36,6 +38,8 @@ on:
- 'scripts/tests/test_e2e_test_images.py'
- 'scripts/collect_e2e_container_logs.py'
- 'scripts/tests/test_e2e_container_logs.py'
+ - 'scripts/ci_browser_proof_only.py'
+ - 'scripts/tests/test_ci_browser_proof_only.py'
workflow_dispatch:
# Let branch runs finish so busy main and release branches retain verdicts.
@@ -49,8 +53,39 @@ permissions:
contents: read
jobs:
+ scope:
+ name: Detect browser receipt-only changes
+ runs-on: ubuntu-24.04
+ timeout-minutes: 5
+ outputs:
+ proof_only: ${{ steps.diff.outputs.proof_only }}
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ fetch-depth: 0
+
+ - name: Check shipped docs before dependency work
+ run: python3 scripts/check_docs_mirror.py
+
+ - name: Validate browser receipt-only CI admission
+ run: python3 scripts/tests/test_ci_browser_proof_only.py
+
+ - name: Read the complete tree diff
+ id: diff
+ env:
+ DIFF_BASE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+ DIFF_HEAD: ${{ github.sha }}
+ run: |
+ set -euo pipefail
+ proof_only=$(python3 scripts/ci_browser_proof_only.py --base "$DIFF_BASE" --head "$DIFF_HEAD")
+ echo "proof_only=$proof_only" >> "$GITHUB_OUTPUT"
+
tier-selection:
name: Validate E2E tier selection
+ needs: scope
+ if: needs.scope.outputs.proof_only != 'true'
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
@@ -103,6 +138,8 @@ jobs:
offline-org-provisioning:
name: Offline Organization provisioning
+ needs: scope
+ if: needs.scope.outputs.proof_only != 'true'
# Fixture acceptance only, not quarantine promotion or private RBAC proof.
runs-on: ubuntu-24.04
timeout-minutes: 25
@@ -518,6 +555,7 @@ jobs:
runs-on: ubuntu-24.04
timeout-minutes: 5
needs:
+ - scope
- tier-selection
- test-images
- e2e
@@ -530,7 +568,29 @@ jobs:
# this verdict. Mechanism and promotion rule: PROBATION_SPECS in
# tests/integration/e2e-tiering.mjs.
- name: Check E2E results
+ env:
+ PROOF_ONLY: ${{ needs.scope.outputs.proof_only }}
run: |
+ if [ "${{ needs.scope.result }}" != "success" ]; then
+ echo "E2E change-scope admission did not pass."
+ exit 1
+ fi
+ if [ "$PROOF_ONLY" = "true" ]; then
+ # A skip is not a test pass. Require the expected all-skipped
+ # topology; never use a receipt to clear a failed runtime job.
+ for result in "${{ needs.tier-selection.result }}" "${{ needs.test-images.result }}" "${{ needs.e2e.result }}" "${{ needs.agent-registration.result }}"; do
+ if [ "$result" != "skipped" ]; then
+ echo "Unexpected runtime result for a browser receipt-only diff: $result"
+ exit 1
+ fi
+ done
+ echo "Browser receipt-only tree diff; runtime E2E is not applicable. Canonical Governance still validates evidence."
+ exit 0
+ fi
+ if [ "$PROOF_ONLY" != "false" ]; then
+ echo "E2E change scope is unknown; no runtime success is established."
+ exit 1
+ fi
if [ "${{ needs.tier-selection.result }}" != "success" ]; then
echo "E2E tier selection is invalid (result: ${{ needs.tier-selection.result }})"
exit 1
diff --git a/scripts/ci_browser_proof_only.py b/scripts/ci_browser_proof_only.py
new file mode 100644
index 0000000000..28a5d32075
--- /dev/null
+++ b/scripts/ci_browser_proof_only.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Recognise receipt-only tree changes, never substitute receipts for source tests.
+
+Canonical Governance still validates these files. Runtime CI can be omitted only
+when the complete tree diff contains nothing but browser evidence JSON. Any
+source, dependency, workflow, documentation or unreadable diff retains runtime CI.
+"""
+
+import argparse
+import re
+import subprocess
+import sys
+
+
+COMMIT = re.compile(r"[0-9a-f]{40}")
+RECEIPT = re.compile(rb"frontend-modern/browser-verification/[A-Za-z0-9_-]+\.json")
+
+
+def receipt_only_paths(paths):
+ return bool(paths) and all(RECEIPT.fullmatch(path) is not None for path in paths)
+
+
+def receipt_only_diff(base, head):
+ if not COMMIT.fullmatch(base) or not COMMIT.fullmatch(head):
+ return False
+ try:
+ # Null delimiters and disabled rename detection prevent quoted or
+ # renamed source paths from disappearing into a receipt-only list.
+ result = subprocess.run(
+ ["git", "diff", "--no-ext-diff", "--no-renames", "--name-only", "-z",
+ base, head, "--"],
+ capture_output=True, timeout=30, check=False,
+ )
+ except (OSError, subprocess.TimeoutExpired):
+ print("Tree diff unavailable; retaining runtime CI.", file=sys.stderr)
+ return False
+ if result.returncode != 0 or not result.stdout.endswith(b"\0"):
+ return False
+ return receipt_only_paths(result.stdout[:-1].split(b"\0"))
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--base", required=True)
+ parser.add_argument("--head", required=True)
+ args = parser.parse_args()
+ print("true" if receipt_only_diff(args.base, args.head) else "false")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/tests/test_ci_browser_proof_only.py b/scripts/tests/test_ci_browser_proof_only.py
new file mode 100644
index 0000000000..15dc8e812d
--- /dev/null
+++ b/scripts/tests/test_ci_browser_proof_only.py
@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Execute receipt-only diff admission and the workflows' actual verdict paths."""
+
+import importlib.util
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import tempfile
+import unittest
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SCRIPT = ROOT / "scripts/ci_browser_proof_only.py"
+BUILD = ROOT / ".github/workflows/build-and-test.yml"
+E2E = ROOT / ".github/workflows/test-e2e.yml"
+SPEC = importlib.util.spec_from_file_location("ci_browser_proof_only", SCRIPT)
+SCOPE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(SCOPE)
+RECEIPT = "frontend-modern/browser-verification/2026-10-14-proof.json"
+JOBS = ("tier-selection", "test-images", "e2e", "agent-registration")
+
+
+def job_block(workflow, name):
+ match = re.search(rf"^ {re.escape(name)}:\n(.*?)(?=^ [\w-]+:\n|\Z)",
+ workflow, re.M | re.S)
+ if match is None:
+ raise AssertionError(f"missing workflow job {name}")
+ return match.group(1)
+
+
+def step_script(block, name):
+ step = re.split(r"(?m)^ - name: ", block)[1:]
+ selected = next(part for part in step if part.startswith(name + "\n"))
+ return "\n".join(line[10:] for line in selected.split(" run: |\n", 1)[1].splitlines())
+
+
+def interpolate(script, expressions):
+ return re.sub(r"\$\{\{\s*(.*?)\s*\}\}", lambda m: expressions[m[1]], script)
+
+
+class ReceiptScopeTest(unittest.TestCase):
+ def test_only_top_level_receipt_json_is_eligible(self):
+ paths = [RECEIPT.encode(), b"frontend-modern/browser-verification/a07b57622067316f.json"]
+ self.assertTrue(SCOPE.receipt_only_paths(paths))
+ self.assertFalse(SCOPE.receipt_only_paths([]))
+
+ def test_source_graph_tests_controls_docs_and_lookalikes_retain_runtime(self):
+ for path in (
+ "frontend-modern/src/components/Machines.tsx", "frontend-modern/public/docs/VM_DISK_MONITORING.md",
+ "frontend-modern/index.html", "frontend-modern/package.json", "frontend-modern/package-lock.json",
+ "tests/integration/package-lock.json", "tests/integration/tests/recovery.spec.ts",
+ "internal/api/server.go", "internal/api/embed.json", "go.mod", "go.sum", "Dockerfile",
+ "scripts/ci_browser_proof_only.py", "scripts/tests/test_ci_browser_proof_only.py",
+ ".github/workflows/build-and-test.yml", ".github/workflows/test-e2e.yml", "docs/guide.md",
+ "frontend-modern/browser-verification.json", "frontend-modern/browser-verification/nested/a.json",
+ "frontend-modern/browser-verification/a.ts", "frontend-modern/browser-verification/.json",
+ "frontend-modern/browser-verification/a.json\ninternal/api/server.go",
+ ):
+ with self.subTest(path=path):
+ self.assertFalse(SCOPE.receipt_only_paths([RECEIPT.encode(), path.encode()]))
+
+ def test_missing_invalid_empty_failed_and_incomplete_diffs_retain_runtime(self):
+ for base, head in (("", "a" * 40), ("HEAD^", "a" * 40), ("a" * 40, "main")):
+ with patch.object(SCOPE.subprocess, "run") as run:
+ self.assertFalse(SCOPE.receipt_only_diff(base, head))
+ run.assert_not_called()
+ for output, code in ((b"", 0), (RECEIPT.encode(), 0), (RECEIPT.encode() + b"\0", 1)):
+ with patch.object(SCOPE.subprocess, "run", return_value=subprocess.CompletedProcess([], code, output)):
+ self.assertFalse(SCOPE.receipt_only_diff("a" * 40, "b" * 40))
+ for error in (OSError("fixture unavailable"), subprocess.TimeoutExpired("git", 30)):
+ with patch.object(SCOPE.subprocess, "run", side_effect=error):
+ self.assertFalse(SCOPE.receipt_only_diff("a" * 40, "b" * 40))
+
+ def test_complete_null_delimited_diff_is_consumed_without_rename_or_external_diff(self):
+ output = (RECEIPT.encode() + b"\0") * 4000 + b"internal/api/server.go\0"
+ with patch.object(SCOPE.subprocess, "run", return_value=subprocess.CompletedProcess([], 0, output)) as run:
+ self.assertFalse(SCOPE.receipt_only_diff("a" * 40, "b" * 40))
+ self.assertEqual(run.call_args.args[0], [
+ "git", "diff", "--no-ext-diff", "--no-renames", "--name-only", "-z",
+ "a" * 40, "b" * 40, "--",
+ ])
+
+
+class GitTreeScopeTest(unittest.TestCase):
+ def setUp(self):
+ self.temp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temp.cleanup)
+ self.repo = Path(self.temp.name)
+ self.git("init", "-q", "--initial-branch=main")
+ for name in ("scripts/ci_browser_proof_only.py", "scripts/go-test-compile-required.sh"):
+ path = self.repo / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(ROOT / name, path)
+ self.write("internal/api/fixture.go", "package fixture\n")
+ self.base = self.commit()
+
+ def git(self, *args):
+ return subprocess.check_output(
+ ["git", "-c", "user.name=CI fixture", "-c", "[email protected]",
+ "-c", "core.hooksPath=/dev/null", *args], cwd=self.repo,
+ stderr=subprocess.PIPE, text=True,
+ ).strip()
+
+ def write(self, name, text):
+ path = self.repo / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text)
+
+ def commit(self):
+ self.git("add", "-A")
+ self.git("commit", "-q", "-m", "Fixture tree change")
+ return self.git("rev-parse", "HEAD")
+
+ def scope(self, base, head):
+ result = subprocess.run(
+ ["python3", str(SCRIPT), "--base", base, "--head", head],
+ cwd=self.repo, capture_output=True, text=True, check=True, timeout=10,
+ )
+ return result.stdout.strip()
+
+ def test_real_git_receipt_add_edit_delete_and_empty_tree(self):
+ self.assertEqual(self.scope(self.base, self.base), "false")
+ self.assertEqual(self.scope("0" * 40, self.base), "false")
+ self.write(RECEIPT, "{}\n")
+ added = self.commit()
+ self.assertEqual(self.scope(self.base, added), "true")
+ self.write(RECEIPT, '{"updated":true}\n')
+ edited = self.commit()
+ self.assertEqual(self.scope(added, edited), "true")
+ (self.repo / RECEIPT).unlink()
+ deleted = self.commit()
+ self.assertEqual(self.scope(edited, deleted), "true")
+
+ def test_real_git_full_range_does_not_hide_source_behind_a_later_receipt(self):
+ self.write("internal/api/fixture.go", "package fixture\nvar Updated = true\n")
+ source = self.commit()
+ self.write(RECEIPT, "{}\n")
+ proof = self.commit()
+ self.assertEqual(self.scope(source, proof), "true")
+ self.assertEqual(self.scope(self.base, proof), "false")
+
+ def test_real_git_rename_to_source_and_quoted_filename_cannot_skip(self):
+ self.write(RECEIPT, "{}\n")
+ receipt = self.commit()
+ target = self.repo / "frontend-modern/src/fixture.json"
+ target.parent.mkdir(parents=True, exist_ok=True)
+ (self.repo / RECEIPT).rename(target)
+ renamed = self.commit()
+ self.assertEqual(self.scope(receipt, renamed), "false")
+ self.write('frontend-modern/src/quoted\n"fixture.json', "{}\n")
+ quoted = self.commit()
+ self.assertEqual(self.scope(renamed, quoted), "false")
+
+ def classify(self, base, head):
+ script = step_script(job_block(BUILD.read_text(), "changes"), "Classify changed files")
+ script = interpolate(script, {
+ "github.event_name": "pull_request", "github.event.pull_request.base.sha": base,
+ "github.event.before": base, "github.sha": head,
+ })
+ output = self.repo / "outputs"
+ if output.exists():
+ output.unlink()
+ result = subprocess.run(["bash", "-c", script], cwd=self.repo, capture_output=True,
+ text=True, timeout=10, env={**os.environ, "GITHUB_OUTPUT": str(output)})
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ return dict(line.split("=", 1) for line in output.read_text().splitlines())
+
+ def test_actual_build_classifier_omits_only_receipt_runtime_checks(self):
+ self.write(RECEIPT, "{}\n")
+ proof = self.commit()
+ self.assertEqual(self.classify(self.base, proof), {
+ "code": "false", "frontend_deps": "false", "go_compile": "false",
+ })
+ self.write("frontend-modern/package-lock.json", "{}\n")
+ graph = self.commit()
+ self.assertEqual(self.classify(self.base, graph), {
+ "code": "true", "frontend_deps": "true", "go_compile": "false",
+ })
+ self.assertEqual(self.classify("0" * 40, graph), {
+ "code": "true", "frontend_deps": "true", "go_compile": "true",
+ })
+ self.write("internal/api/fixture.go", "package fixture\nvar Updated = true\n")
+ source = self.commit()
+ self.assertEqual(self.classify(graph, source), {
+ "code": "true", "frontend_deps": "false", "go_compile": "true",
+ })
+
+
+class WorkflowScopeTest(unittest.TestCase):
+ def test_scope_is_checked_before_runtime_and_preserves_required_governance(self):
+ e2e = E2E.read_text()
+ scope = job_block(e2e, "scope")
+ self.assertIn("fetch-depth: 0", scope)
+ self.assertIn("persist-credentials: false", scope)
+ self.assertIn("timeout-minutes: 5", scope)
+ self.assertIn('proof_only=$(python3 scripts/ci_browser_proof_only.py --base "$DIFF_BASE" --head "$DIFF_HEAD")', scope)
+ self.assertNotIn("continue-on-error", scope)
+ for name in ("tier-selection", "offline-org-provisioning"):
+ job = job_block(e2e, name)
+ self.assertIn("needs: scope", job)
+ self.assertIn("if: needs.scope.outputs.proof_only != 'true'", job)
+ for event in ("pull_request", "push"):
+ block = re.split(r"(?m)^ \S", e2e.split(f" {event}:\n", 1)[1], maxsplit=1)[0]
+ for path in ("scripts/ci_browser_proof_only.py", "scripts/tests/test_ci_browser_proof_only.py"):
+ self.assertIn(f"'{path}'", block)
+ verdict = job_block(e2e, "e2e-verdict")
+ self.assertIn(" - scope\n", verdict)
+ self.assertIn("if: always()", verdict)
+ self.assertIn("PROOF_ONLY: ${{ needs.scope.outputs.proof_only }}", verdict)
+ self.assertNotIn("${{ needs.scope.outputs.proof_only }}", step_script(verdict, "Check E2E results"))
+ build = BUILD.read_text()
+ self.assertIn("python3 scripts/tests/test_ci_browser_proof_only.py", job_block(build, "changes"))
+ self.assertNotIn("if:", job_block(build, "secret-scan"))
+ governance = (ROOT / ".github/workflows/canonical-governance.yml").read_text()
+ self.assertIn("--base", governance)
+ self.assertIn("scripts/release_control/browser_verification_guard.py", governance)
+ self.assertNotIn("ci_browser_proof_only", governance)
+
+ def verdict(self, proof_only, results, scope="success"):
+ script = step_script(job_block(E2E.read_text(), "e2e-verdict"), "Check E2E results")
+ script = interpolate(script, {"needs.scope.result": scope,
+ **{f"needs.{job}.result": value for job, value in results.items()}})
+ return subprocess.run(["bash", "-c", script], capture_output=True, text=True,
+ timeout=5, env={**os.environ, "PROOF_ONLY": proof_only})
+
+ def test_actual_verdict_names_receipt_skip_without_claiming_runtime_pass(self):
+ result = self.verdict("true", dict.fromkeys(JOBS, "skipped"))
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn("not applicable", result.stdout)
+ self.assertNotIn("passed", result.stdout)
+ for job in JOBS:
+ for state in ("success", "failure", "cancelled", ""):
+ results = dict.fromkeys(JOBS, "skipped")
+ results[job] = state
+ with self.subTest(job=job, state=state):
+ self.assertNotEqual(self.verdict("true", results).returncode, 0)
+
+ def test_actual_runtime_verdict_still_requires_every_existing_success(self):
+ results = dict.fromkeys(JOBS, "success")
+ self.assertEqual(self.verdict("false", results).returncode, 0)
+ for job in JOBS:
+ for state in ("failure", "cancelled", "skipped", ""):
+ adverse = {**results, job: state}
+ with self.subTest(job=job, state=state):
+ self.assertNotEqual(self.verdict("false", adverse).returncode, 0)
+
+ def test_unknown_or_failed_scope_cannot_report_runtime_success(self):
+ for proof in ("", "unknown", "true\nfalse"):
+ self.assertNotEqual(self.verdict(proof, dict.fromkeys(JOBS, "success")).returncode, 0)
+ for scope in ("failure", "cancelled", "skipped", ""):
+ for proof, state in (("true", "skipped"), ("false", "success")):
+ with self.subTest(scope=scope, proof=proof):
+ self.assertNotEqual(self.verdict(proof, dict.fromkeys(JOBS, state), scope).returncode, 0)
+
+
+if __name__ == "__main__":
+ unittest.main()