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.

Build Core E2E test images once per exact workflow run

pulse-triage[bot]440137890e5a
diff --git a/.github/workflows/test-e2e.yml b/.github/workflows/test-e2e.yml
index 64dfe19b65..5db15dc616 100644
--- a/.github/workflows/test-e2e.yml
+++ b/.github/workflows/test-e2e.yml
@@ -14,6 +14,8 @@ on:
- '.github/workflows/test-e2e.yml'
- 'scripts/playwright-apt.conf'
- 'scripts/tests/test_playwright_acquisition.py'
+ - 'scripts/e2e_test_images.py'
+ - 'scripts/tests/test_e2e_test_images.py'
push:
branches:
- main
@@ -28,6 +30,8 @@ on:
- '.github/workflows/test-e2e.yml'
- 'scripts/playwright-apt.conf'
- 'scripts/tests/test_playwright_acquisition.py'
+ - 'scripts/e2e_test_images.py'
+ - 'scripts/tests/test_e2e_test_images.py'
workflow_dispatch:
# Let branch runs finish so busy main and release branches retain verdicts.
@@ -55,6 +59,9 @@ jobs:
- name: Check shipped docs before dependency work
run: python3 scripts/check_docs_mirror.py
+ - name: Validate shared E2E image admission
+ run: python3 scripts/tests/test_e2e_test_images.py
+
- name: Validate browser dependency acquisition policy
run: python3 scripts/tests/test_playwright_acquisition.py
@@ -148,9 +155,41 @@ jobs:
path: tests/integration/playwright-report/multi-tenant-diagnostic/
retention-days: 3
+ test-images:
+ name: Build source-bound E2E images once
+ needs: tier-selection
+ runs-on: ubuntu-24.04
+ timeout-minutes: 30
+ outputs:
+ artifact-id: ${{ steps.images.outputs.artifact-id }}
+ manifest-sha256: ${{ steps.bundle.outputs.manifest-sha256 }}
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+
+ # Same provider, pins and e2e_runtime contract as the former nine builds.
+ # A provider refusal remains terminal: no mirror, login or pull retry.
+ - name: Build and bind the test images
+ id: bundle
+ run: python3 scripts/e2e_test_images.py build "$RUNNER_TEMP/pulse-e2e-images"
+
+ - name: Upload this run's exact test images
+ id: images
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: e2e-test-images-${{ github.sha }}-${{ github.run_attempt }}
+ path: |
+ ${{ runner.temp }}/pulse-e2e-images/manifest.json
+ ${{ runner.temp }}/pulse-e2e-images/images.tar.gz
+ retention-days: 1
+ compression-level: 0
+ if-no-files-found: error
+
e2e:
name: Playwright Core E2E (shard ${{ matrix.shard }}/8)
- needs: tier-selection
+ needs: [tier-selection, test-images]
runs-on: ubuntu-24.04
timeout-minutes: 60
strategy:
@@ -158,6 +197,9 @@ jobs:
matrix:
shard: [1, 2, 3, 4, 5, 6, 7, 8]
+ env:
+ PULSE_E2E_SEED_IMAGE: pulse-e2e-seed:test
+
steps:
- name: Checkout code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -192,12 +234,17 @@ jobs:
working-directory: internal/cloudcp/portal/frontend
run: npm ci
- - name: Build Docker images for test environment
- # GO_BUILD_TAGS="" drops the release build tag so the suite can enable
- # mock fixtures; release-tag gating has its own -tags release Go tests.
- run: |
- docker build -t pulse:test --target e2e_runtime --build-arg GO_BUILD_TAGS="" .
- docker build -t pulse-mock-github:test ./tests/integration/mock-github-server
+ - name: Download this run's exact test images
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+ with:
+ artifact-ids: ${{ needs.test-images.outputs.artifact-id }}
+ path: ${{ runner.temp }}/pulse-e2e-images
+ merge-multiple: true
+
+ - name: Admit the source-bound test images
+ env:
+ PULSE_E2E_MANIFEST_SHA256: ${{ needs.test-images.outputs.manifest-sha256 }}
+ run: python3 scripts/e2e_test_images.py load "$RUNNER_TEMP/pulse-e2e-images"
- name: Start test containers
working-directory: tests/integration
@@ -323,8 +370,12 @@ jobs:
agent-registration:
name: Agent registration lifecycle
+ needs: [tier-selection, test-images]
runs-on: ubuntu-24.04
timeout-minutes: 30
+ env:
+ PULSE_E2E_SEED_IMAGE: pulse-e2e-seed:test
+
steps:
- name: Checkout code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -357,10 +408,17 @@ jobs:
working-directory: internal/cloudcp/portal/frontend
run: npm ci
- - name: Build test images
- run: |
- docker build -t pulse:test --target e2e_runtime --build-arg GO_BUILD_TAGS="" .
- docker build -t pulse-mock-github:test ./tests/integration/mock-github-server
+ - name: Download this run's exact test images
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+ with:
+ artifact-ids: ${{ needs.test-images.outputs.artifact-id }}
+ path: ${{ runner.temp }}/pulse-e2e-images
+ merge-multiple: true
+
+ - name: Admit the source-bound test images
+ env:
+ PULSE_E2E_MANIFEST_SHA256: ${{ needs.test-images.outputs.manifest-sha256 }}
+ run: python3 scripts/e2e_test_images.py load "$RUNNER_TEMP/pulse-e2e-images"
- name: Start non-mock test container
working-directory: tests/integration
@@ -411,6 +469,7 @@ jobs:
timeout-minutes: 5
needs:
- tier-selection
+ - test-images
- e2e
- agent-registration
if: always()
@@ -426,6 +485,10 @@ jobs:
echo "E2E tier selection is invalid (result: ${{ needs.tier-selection.result }})"
exit 1
fi
+ if [ "${{ needs.test-images.result }}" != "success" ]; then
+ echo "Source-bound E2E test images were not produced (result: ${{ needs.test-images.result }})"
+ exit 1
+ fi
if [ "${{ needs.e2e.result }}" != "success" ]; then
echo "Stable-tier E2E shards did not all pass (result: ${{ needs.e2e.result }})"
exit 1
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index 4395c4d9ad..97f95ddf4d 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -15,6 +15,35 @@
## Purpose
+### Core E2E images are built once and admitted in the same run
+
+The secret-free Core E2E workflow builds its existing `e2e_runtime` server and
+mock GitHub images once after tier validation. It also pulls the unchanged,
+committed Alpine seed pin once. The eight stable shards and non-mock agent
+registration job load the same short-retention, current-run artifact by its
+producer's immutable artifact ID; they do not select another run, image cache,
+registry, credential or rebuild fallback. Local compose keeps its pinned seed
+image default. Each job retains its own containers, data and browser sessions.
+
+Before Docker load, the helper verifies the producer job's manifest digest,
+exact checkout/run/attempt, committed seed pin, three fixed image IDs, archive
+size and archive digest. After load it verifies Linux amd64, the producer's
+image IDs and source revision labels on both built images. A missing, changed,
+foreign or failed bundle stops the job. Failed production stops fan-out and
+fails the final verdict; all eight stable shards and agent registration must
+still pass. Browser acquisition and test deadlines, probation rules, registry
+pins and production/release paths are unchanged. Provider refusals stay terminal:
+there is no login, alternate registry or pull retry.
+
+`scripts/tests/test_e2e_test_images.py` exercises real tar/gzip/hash/filesystem
+production and admission with a Docker command double, exact command arguments,
+source/run/attempt isolation, changed/truncated/oversized/symlink bytes, wrong
+platform/revision/image IDs, terminal failures without replay and fail-closed
+workflow fan-out/verdict mutants. This is source and orchestration proof, not
+real Docker execution, hosted artifact transfer or a completed user journey.
+Containing hosted production, load/start and all journey verdicts remain the
+operational acceptance result. These images are not release artifacts.
+
### Existing auto-update timers are discovered without changing consent
Server installer timer discovery is a bounded, exact-unit `systemctl` inventory.
diff --git a/docs/release-control/v6/internal/subsystems/registry.json b/docs/release-control/v6/internal/subsystems/registry.json
index c8055357c4..dc127fc759 100644
--- a/docs/release-control/v6/internal/subsystems/registry.json
+++ b/docs/release-control/v6/internal/subsystems/registry.json
@@ -4485,6 +4485,7 @@
".github/workflows/release-dry-run.yml",
".github/workflows/release-lifecycle-rehearsal.yml",
".github/workflows/retry-release-convergence.yml",
+ ".github/workflows/test-e2e.yml",
".github/workflows/update-demo-server.yml",
".github/workflows/validate-release-assets.yml",
"cmd/pulse-control-plane/main.go",
@@ -4545,6 +4546,7 @@
"scripts/dev-deploy-agent.sh",
"scripts/dev-launchd-setup.sh",
"scripts/dev-launchd-wrapper.sh",
+ "scripts/e2e_test_images.py",
"scripts/generate-release-notes.sh",
"scripts/go-mod-download.sh",
"scripts/hot-dev-bg.sh",
@@ -4598,6 +4600,7 @@
"scripts/uninstall-sensor-proxy.sh",
"scripts/validate-release.sh",
"scripts/verify-github-release-integrity.sh",
+ "tests/integration/docker-compose.test.yml",
"tests/integration/playwright.config.ts",
"tests/integration/QUICK_START.md",
"tests/integration/README.md",
@@ -5151,6 +5154,21 @@
"exact_files": [
"scripts/tests/test_go_mod_download.py"
]
+ },
+ {
+ "id": "e2e-image-distribution",
+ "label": "same-run source-bound E2E image distribution proof",
+ "match_prefixes": [],
+ "match_files": [
+ ".github/workflows/test-e2e.yml",
+ "scripts/e2e_test_images.py",
+ "tests/integration/docker-compose.test.yml"
+ ],
+ "allow_same_subsystem_tests": false,
+ "test_prefixes": [],
+ "exact_files": [
+ "scripts/tests/test_e2e_test_images.py"
+ ]
}
],
"match_files": null
diff --git a/scripts/e2e_test_images.py b/scripts/e2e_test_images.py
new file mode 100644
index 0000000000..afd819956b
--- /dev/null
+++ b/scripts/e2e_test_images.py
@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Build once, then admit the same run/source-bound E2E images in every job.
+
+This is a same-run artifact, not a registry mirror or a cross-run image cache.
+Docker failures are terminal: no login, alternate registry, pull retry or rebuild
+fallback is performed. Only the existing secret-free E2E stack is distributed.
+"""
+
+import argparse
+import gzip
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[1]
+COMPOSE = ROOT / "tests/integration/docker-compose.test.yml"
+ARCHIVE = "images.tar.gz"
+MANIFEST = "manifest.json"
+IMAGES = ("pulse:test", "pulse-mock-github:test", "pulse-e2e-seed:test")
+REVISION_LABEL = "org.opencontainers.image.revision"
+SHA256 = r"[0-9a-f]{64}"
+MAX_ARCHIVE_BYTES = 1024 * 1024 * 1024
+
+
+def run(*args, capture=False):
+ return subprocess.run(
+ args, cwd=ROOT, check=True, text=True,
+ stdout=subprocess.PIPE if capture else None,
+ ).stdout
+
+
+def digest(path):
+ with path.open("rb") as stream:
+ return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def seed_image():
+ # Follow the committed compose pin, never an environment/registry override.
+ block = COMPOSE.read_text().split(" seed-bootstrap-token:\n", 1)[1].split("\n mock-github:", 1)[0]
+ match = re.search(
+ r"(?m)^ image: \$\{PULSE_E2E_SEED_IMAGE:-(alpine:[0-9.]+@sha256:" + SHA256 + r")\}$",
+ block,
+ )
+ if not match:
+ raise ValueError("E2E seed image must retain its exact committed Alpine pin")
+ return match[1]
+
+
+def binding():
+ source = os.environ["GITHUB_SHA"]
+ run_id = os.environ["GITHUB_RUN_ID"]
+ attempt = os.environ["GITHUB_RUN_ATTEMPT"]
+ if not re.fullmatch(r"[0-9a-f]{40}", source):
+ raise ValueError("Invalid E2E checkout identity")
+ if any(not re.fullmatch(r"[1-9][0-9]*", value) for value in (run_id, attempt)):
+ raise ValueError("Invalid E2E run identity")
+ if run("git", "rev-parse", "HEAD", capture=True).strip() != source:
+ raise ValueError("E2E checkout does not match this workflow source")
+ return {"source_sha": source, "run_id": run_id, "run_attempt": attempt}
+
+
+def inspect_images(source):
+ ids = {}
+ for image in IMAGES:
+ record = json.loads(run("docker", "image", "inspect", "--format", "{{json .}}", image, capture=True))
+ if not re.fullmatch("sha256:" + SHA256, record["Id"]):
+ raise ValueError("Invalid E2E image identity")
+ if record["Os"] != "linux" or record["Architecture"] != "amd64":
+ raise ValueError("E2E images must target Linux amd64")
+ if image != "pulse-e2e-seed:test":
+ labels = record["Config"].get("Labels") or {}
+ if labels.get(REVISION_LABEL) != source:
+ raise ValueError("E2E image revision does not match the checkout")
+ ids[image] = record["Id"]
+ return ids
+
+
+def build(directory, identity):
+ directory.mkdir(parents=True, exist_ok=False)
+ label = f"{REVISION_LABEL}={identity['source_sha']}"
+ # Keep the e2e_runtime target and empty release tags: both mock and
+ # non-mock registration jobs already used this exact build contract.
+ run("docker", "build", "--platform=linux/amd64", "--label", label,
+ "-t", IMAGES[0], "--target", "e2e_runtime", "--build-arg", "GO_BUILD_TAGS=", ".")
+ run("docker", "build", "--platform=linux/amd64", "--label", label,
+ "-t", IMAGES[1], "./tests/integration/mock-github-server")
+ pinned_seed = seed_image()
+ run("docker", "image", "pull", "--platform=linux/amd64", pinned_seed)
+ run("docker", "image", "tag", pinned_seed, IMAGES[2])
+ ids = inspect_images(identity["source_sha"])
+ raw = directory / "images.tar"
+ run("docker", "image", "save", "--output", str(raw), *IMAGES)
+ archive = directory / ARCHIVE
+ with raw.open("rb") as incoming, archive.open("xb") as outgoing:
+ with gzip.GzipFile(filename="", fileobj=outgoing, mode="wb", compresslevel=1, mtime=0) as compressed:
+ shutil.copyfileobj(incoming, compressed, length=1024 * 1024)
+ raw.unlink()
+ size = archive.stat().st_size
+ if not 0 < size <= MAX_ARCHIVE_BYTES:
+ raise ValueError("E2E image bundle exceeds the transfer budget")
+ manifest = {
+ "schema_version": 1, **identity, "seed_image": pinned_seed, "images": ids,
+ "archive_sha256": digest(archive), "archive_bytes": size,
+ }
+ path = directory / MANIFEST
+ with path.open("x") as stream:
+ json.dump(manifest, stream, sort_keys=True)
+ stream.write("\n")
+ # The job output is the trust anchor, not a checksum supplied beside bytes.
+ with Path(os.environ["GITHUB_OUTPUT"]).open("a") as stream:
+ stream.write(f"manifest-sha256={digest(path)}\n")
+ print("Built one source-bound E2E bundle (two builds and the pinned seed image)")
+
+
+def load(directory, identity):
+ expected = os.environ["PULSE_E2E_MANIFEST_SHA256"]
+ if not re.fullmatch(SHA256, expected):
+ raise ValueError("Missing or invalid producer manifest identity")
+ manifest_path = directory / MANIFEST
+ archive = directory / ARCHIVE
+ for path in (manifest_path, archive):
+ if path.is_symlink() or not path.is_file():
+ raise ValueError("E2E bundle files must be regular files")
+ if manifest_path.stat().st_size > 16384 or digest(manifest_path) != expected:
+ raise ValueError("E2E manifest differs from the producer job output")
+ manifest = json.loads(manifest_path.read_text())
+ keys = {"schema_version", *identity, "seed_image", "images", "archive_sha256", "archive_bytes"}
+ if not isinstance(manifest, dict) or set(manifest) != keys or type(manifest["schema_version"]) is not int or manifest["schema_version"] != 1:
+ raise ValueError("Unsupported E2E manifest")
+ if any(manifest[key] != value for key, value in identity.items()):
+ raise ValueError("E2E bundle belongs to another source, run or attempt")
+ if manifest["seed_image"] != seed_image():
+ raise ValueError("E2E seed image differs from the committed compose pin")
+ ids = manifest["images"]
+ if not isinstance(ids, dict) or set(ids) != set(IMAGES):
+ raise ValueError("E2E bundle must contain the three fixed image identities")
+ if any(not isinstance(value, str) or not re.fullmatch("sha256:" + SHA256, value) for value in ids.values()):
+ raise ValueError("Invalid producer E2E image identities")
+ size = archive.stat().st_size
+ if type(manifest["archive_bytes"]) is not int or not 0 < size <= MAX_ARCHIVE_BYTES or size != manifest["archive_bytes"]:
+ raise ValueError("E2E image archive size does not match the producer")
+ if not isinstance(manifest["archive_sha256"], str) or not re.fullmatch(SHA256, manifest["archive_sha256"]):
+ raise ValueError("Invalid producer archive identity")
+ if digest(archive) != manifest["archive_sha256"]:
+ raise ValueError("E2E image archive differs from the producer")
+ # No load, start, pull or build occurs before all admission checks pass.
+ run("docker", "image", "load", "--input", str(archive))
+ if inspect_images(identity["source_sha"]) != ids:
+ raise ValueError("Loaded E2E image identities differ from the producer")
+ print("Admitted the producer's exact E2E images for this source/run/attempt")
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("operation", choices=("build", "load"))
+ parser.add_argument("directory", type=Path)
+ args = parser.parse_args()
+ try:
+ identity = binding()
+ (build if args.operation == "build" else load)(args.directory, identity)
+ except (ValueError, KeyError, IndexError, OSError, subprocess.CalledProcessError) as error:
+ print(f"E2E image admission failed: {error}", file=sys.stderr)
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/release_control/dev_runtime_governance_test.py b/scripts/release_control/dev_runtime_governance_test.py
index 2a1f40af72..2365160578 100644
--- a/scripts/release_control/dev_runtime_governance_test.py
+++ b/scripts/release_control/dev_runtime_governance_test.py
@@ -5,6 +5,25 @@ from subsystem_lookup import lookup_paths
class DevRuntimeGovernanceTest(unittest.TestCase):
+ def test_e2e_image_distribution_has_exact_scoped_proof(self) -> None:
+ files = [
+ ".github/workflows/test-e2e.yml",
+ "scripts/e2e_test_images.py",
+ "tests/integration/docker-compose.test.yml",
+ ]
+ result = lookup_paths(files)
+ self.assertEqual(result["unowned_runtime_files"], [])
+ for entry in result["files"]:
+ self.assertEqual(entry["classification"], "runtime")
+ self.assertEqual(len(entry["matches"]), 1)
+ match = entry["matches"][0]
+ self.assertEqual(match["subsystem"], "deployment-installability")
+ proof = match["verification_requirement"]
+ self.assertEqual(proof["id"], "e2e-image-distribution")
+ self.assertEqual(proof["exact_files"], ["scripts/tests/test_e2e_test_images.py"])
+ self.assertFalse(proof["allow_same_subsystem_tests"])
+ self.assertEqual(proof["test_prefixes"], [])
+
def test_shell_smoke_tests_are_classified_as_tests(self) -> None:
self.assertTrue(is_test_or_fixture("scripts/tests/test-hot-dev-bg.sh"))
self.assertEqual(infer_impacted_subsystems(["scripts/tests/test-hot-dev-bg.sh"]), {})
diff --git a/scripts/tests/test_e2e_test_images.py b/scripts/tests/test_e2e_test_images.py
new file mode 100644
index 0000000000..921157ae93
--- /dev/null
+++ b/scripts/tests/test_e2e_test_images.py
@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""Exercise same-run E2E image production/admission without a registry or daemon."""
+
+import copy
+import gzip
+import importlib.util
+import io
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tarfile
+import tempfile
+import unittest
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SPEC = importlib.util.spec_from_file_location("e2e_test_images", ROOT / "scripts/e2e_test_images.py")
+IMAGES = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(IMAGES)
+WORKFLOW = ROOT / ".github/workflows/test-e2e.yml"
+SOURCE = "a" * 40
+IDENTITY = {"source_sha": SOURCE, "run_id": "1234567", "run_attempt": "2"}
+
+
+def job_block(workflow, job):
+ return re.split(r"(?m)^ \S", workflow.split(f"\n {job}:\n", 1)[1], maxsplit=1)[0]
+
+
+class DockerDouble:
+ """Record real helper invocations; supply local deterministic saved bytes."""
+
+ def __init__(self):
+ self.calls = []
+ self.fail = None
+ self.records = {
+ name: {
+ "Id": "sha256:" + str(index + 1) * 64,
+ "Os": "linux", "Architecture": "amd64",
+ "Config": {"Labels": {IMAGES.REVISION_LABEL: SOURCE}},
+ }
+ for index, name in enumerate(IMAGES.IMAGES)
+ }
+ # Upstream seed bytes have no candidate-specific revision label.
+ self.records["pulse-e2e-seed:test"]["Config"]["Labels"] = None
+
+ def __call__(self, *args, capture=False):
+ self.calls.append(args)
+ if self.fail and args[:len(self.fail)] == self.fail:
+ raise subprocess.CalledProcessError(1, args)
+ if args == ("git", "rev-parse", "HEAD"):
+ return SOURCE + "\n"
+ if args[:3] == ("docker", "image", "inspect"):
+ return json.dumps(self.records[args[-1]])
+ if args[:3] == ("docker", "image", "save"):
+ # Real tar/gzip/file/hash operations run; only the daemon is doubled.
+ with tarfile.open(args[4], "w") as archive:
+ for image in args[5:]:
+ payload = self.records[image]["Id"].encode()
+ item = tarfile.TarInfo(image.replace(":", "-") + ".json")
+ item.size = len(payload)
+ archive.addfile(item, io.BytesIO(payload))
+ return None
+
+
+class E2EImageBundleTest(unittest.TestCase):
+ def setUp(self):
+ self.temp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temp.cleanup)
+ self.directory = Path(self.temp.name) / "bundle"
+ self.output = Path(self.temp.name) / "outputs"
+ self.docker = DockerDouble()
+ self.env = {
+ "GITHUB_SHA": SOURCE, "GITHUB_RUN_ID": IDENTITY["run_id"],
+ "GITHUB_RUN_ATTEMPT": IDENTITY["run_attempt"], "GITHUB_OUTPUT": str(self.output),
+ }
+ self.addCleanup(patch.stopall)
+ patch.dict(os.environ, self.env).start()
+ patch.object(IMAGES, "run", self.docker).start()
+
+ def produce(self):
+ IMAGES.build(self.directory, IDENTITY)
+ value = self.output.read_text().strip().split("=", 1)[1]
+ os.environ["PULSE_E2E_MANIFEST_SHA256"] = value
+ self.docker.calls.clear()
+ return json.loads((self.directory / IMAGES.MANIFEST).read_text())
+
+ def replace_manifest(self, manifest, rebind=True):
+ path = self.directory / IMAGES.MANIFEST
+ path.write_text(json.dumps(manifest))
+ if rebind:
+ os.environ["PULSE_E2E_MANIFEST_SHA256"] = IMAGES.digest(path)
+
+ def assert_refused_before_docker(self):
+ self.docker.calls.clear()
+ with self.assertRaises((ValueError, OSError)):
+ IMAGES.load(self.directory, IDENTITY)
+ self.assertEqual(self.docker.calls, [])
+
+ def test_real_tar_gzip_round_trip_and_exact_commands(self):
+ IMAGES.build(self.directory, IDENTITY)
+ builds = [args for args in self.docker.calls if args[:2] == ("docker", "build")]
+ self.assertEqual(len(builds), 2)
+ self.assertEqual(builds[0], (
+ "docker", "build", "--platform=linux/amd64", "--label",
+ f"{IMAGES.REVISION_LABEL}={SOURCE}", "-t", "pulse:test", "--target",
+ "e2e_runtime", "--build-arg", "GO_BUILD_TAGS=", ".",
+ ))
+ self.assertEqual(builds[1][-3:], ("-t", "pulse-mock-github:test", "./tests/integration/mock-github-server"))
+ pulls = [args for args in self.docker.calls if args[:3] == ("docker", "image", "pull")]
+ self.assertEqual(pulls, [("docker", "image", "pull", "--platform=linux/amd64", IMAGES.seed_image())])
+ saved = next(args for args in self.docker.calls if args[:3] == ("docker", "image", "save"))
+ self.assertEqual(saved[5:], IMAGES.IMAGES)
+ self.assertFalse((self.directory / "images.tar").exists())
+ with gzip.open(self.directory / IMAGES.ARCHIVE, "rb") as stream:
+ with tarfile.open(fileobj=stream, mode="r|") as archive:
+ self.assertEqual([entry.name for entry in archive], [name.replace(":", "-") + ".json" for name in IMAGES.IMAGES])
+ os.environ["PULSE_E2E_MANIFEST_SHA256"] = self.output.read_text().strip().split("=", 1)[1]
+ self.docker.calls.clear()
+ IMAGES.load(self.directory, IDENTITY)
+ self.assertEqual(self.docker.calls[0], ("docker", "image", "load", "--input", str(self.directory / IMAGES.ARCHIVE)))
+ self.assertEqual(len(self.docker.calls), 4) # one load, three identity reads
+ self.assertFalse(any("build" in args or "pull" in args for args in self.docker.calls))
+
+ def test_binding_rejects_another_checkout_and_malformed_run(self):
+ self.assertEqual(IMAGES.binding(), IDENTITY)
+ for key, value in (("GITHUB_SHA", "b" * 40), ("GITHUB_SHA", "main"),
+ ("GITHUB_RUN_ID", "0"), ("GITHUB_RUN_ATTEMPT", "2\n3")):
+ with self.subTest(key=key, value=value), patch.dict(os.environ, {key: value}):
+ with self.assertRaises(ValueError):
+ IMAGES.binding()
+
+ def test_build_load_cli_uses_authenticated_source_binding(self):
+ with patch.object(sys, "argv", ["images", "build", str(self.directory)]):
+ self.assertEqual(IMAGES.main(), 0)
+ os.environ["PULSE_E2E_MANIFEST_SHA256"] = self.output.read_text().strip().split("=", 1)[1]
+ with patch.object(sys, "argv", ["images", "load", str(self.directory)]):
+ self.assertEqual(IMAGES.main(), 0)
+
+ def test_provider_build_pull_save_refusals_are_not_replayed(self):
+ for command in (("docker", "build"), ("docker", "image", "pull"), ("docker", "image", "save")):
+ with self.subTest(command=command):
+ self.directory = Path(self.temp.name) / ("-".join(command))
+ self.docker.calls.clear()
+ self.docker.fail = command
+ with self.assertRaises(subprocess.CalledProcessError):
+ IMAGES.build(self.directory, IDENTITY)
+ self.assertEqual(sum(args[:len(command)] == command for args in self.docker.calls), 1)
+ self.assertFalse((self.directory / IMAGES.MANIFEST).exists())
+ self.assertFalse(self.output.exists())
+
+ def test_build_refuses_existing_destination(self):
+ self.directory.mkdir()
+ with self.assertRaises(FileExistsError):
+ IMAGES.build(self.directory, IDENTITY)
+ self.assertEqual(self.docker.calls, [])
+
+ def test_producer_rejects_wrong_revision_platform_and_id(self):
+ original = copy.deepcopy(self.docker.records)
+ for field, value in (("Architecture", "arm64"), ("Os", "windows"), ("Id", "latest"),
+ ("Config", {"Labels": {IMAGES.REVISION_LABEL: "b" * 40}})):
+ with self.subTest(field=field):
+ self.docker.records = copy.deepcopy(original)
+ self.docker.records["pulse:test"][field] = value
+ with self.assertRaises(ValueError):
+ IMAGES.inspect_images(SOURCE)
+
+ def test_manifest_job_output_is_required_not_a_sidecar_hint(self):
+ self.produce()
+ for value in ("", "a" * 64, "not-a-hash"):
+ with self.subTest(value=value), patch.dict(os.environ, {"PULSE_E2E_MANIFEST_SHA256": value}):
+ self.assert_refused_before_docker()
+
+ def test_changed_manifest_refused_even_with_unchanged_archive(self):
+ manifest = self.produce()
+ manifest["images"]["pulse:test"] = "sha256:" + "4" * 64
+ self.replace_manifest(manifest, rebind=False)
+ self.assert_refused_before_docker()
+
+ def test_other_source_run_attempt_schema_pin_or_images_refused(self):
+ original = self.produce()
+ for field, value in (("source_sha", "b" * 40), ("run_id", "7654321"), ("run_attempt", "1"),
+ ("schema_version", 2), ("schema_version", True), ("seed_image", "alpine:latest"),
+ ("images", {}), ("images", {**original["images"], "other:test": "sha256:" + "f" * 64}),
+ ("images", {**original["images"], "pulse:test": "latest"}),
+ ("archive_bytes", True), ("archive_bytes", 0), ("archive_bytes", "10"),
+ ("archive_sha256", "not-a-hash")):
+ with self.subTest(field=field, value=value):
+ manifest = {**original, field: value}
+ self.replace_manifest(manifest)
+ self.assert_refused_before_docker()
+ self.replace_manifest({**original, "load_command": "anything"})
+ self.assert_refused_before_docker()
+
+ def test_tampered_truncated_and_oversized_archives_never_load(self):
+ self.produce()
+ archive = self.directory / IMAGES.ARCHIVE
+ original = archive.read_bytes()
+ for payload in (original[:-1], original + b"extra", b"x" * len(original)):
+ with self.subTest(bytes=len(payload)):
+ archive.write_bytes(payload)
+ self.assert_refused_before_docker()
+ archive.write_bytes(original)
+ with patch.object(IMAGES, "MAX_ARCHIVE_BYTES", len(original) - 1):
+ self.assert_refused_before_docker()
+
+ def test_missing_symlink_and_oversized_manifest_never_load(self):
+ self.produce()
+ for name in (IMAGES.MANIFEST, IMAGES.ARCHIVE):
+ with self.subTest(file=name):
+ path = self.directory / name
+ old = path.with_suffix(".owned")
+ path.rename(old)
+ self.assert_refused_before_docker()
+ path.symlink_to(old)
+ self.assert_refused_before_docker()
+ path.unlink()
+ old.rename(path)
+ path = self.directory / IMAGES.MANIFEST
+ path.write_bytes(b" " * 16385)
+ os.environ["PULSE_E2E_MANIFEST_SHA256"] = IMAGES.digest(path)
+ self.assert_refused_before_docker()
+
+ def test_load_failure_is_terminal_without_pull_or_rebuild(self):
+ self.produce()
+ self.docker.fail = ("docker", "image", "load")
+ with self.assertRaises(subprocess.CalledProcessError):
+ IMAGES.load(self.directory, IDENTITY)
+ self.assertEqual(self.docker.calls, [("docker", "image", "load", "--input", str(self.directory / IMAGES.ARCHIVE))])
+
+ def test_loaded_image_must_match_source_platform_and_producer_id(self):
+ self.produce()
+ original = copy.deepcopy(self.docker.records)
+ for field, value in (("Architecture", "arm64"), ("Os", "windows"), ("Id", "sha256:" + "e" * 64),
+ ("Config", {"Labels": {IMAGES.REVISION_LABEL: "b" * 40}})):
+ with self.subTest(field=field):
+ self.docker.records = copy.deepcopy(original)
+ self.docker.records["pulse:test"][field] = value
+ self.docker.calls.clear()
+ with self.assertRaises(ValueError):
+ IMAGES.load(self.directory, IDENTITY)
+ self.assertEqual(self.docker.calls[0][:3], ("docker", "image", "load"))
+ self.assertFalse(any("build" in args or "pull" in args for args in self.docker.calls))
+
+ def test_seed_pin_and_local_default_are_preserved(self):
+ source = IMAGES.COMPOSE.read_text()
+ pin = IMAGES.seed_image()
+ self.assertIn("${PULSE_E2E_SEED_IMAGE:-" + pin + "}", source)
+ self.assertNotIn("pull_policy: always", source)
+ with patch.dict(os.environ, {"PULSE_E2E_SEED_IMAGE": "untrusted.example/image:latest"}):
+ self.assertEqual(IMAGES.seed_image(), pin)
+
+
+class E2EImageWorkflowTest(unittest.TestCase):
+ def assert_workflow(self, workflow):
+ producer = job_block(workflow, "test-images")
+ self.assertIn("needs: tier-selection", producer)
+ self.assertIn("timeout-minutes: 30", producer)
+ self.assertIn('python3 scripts/e2e_test_images.py build "$RUNNER_TEMP/pulse-e2e-images"', producer)
+ self.assertIn("artifact-id: ${{ steps.images.outputs.artifact-id }}", producer)
+ self.assertIn("manifest-sha256: ${{ steps.bundle.outputs.manifest-sha256 }}", producer)
+ self.assertIn("if-no-files-found: error", producer)
+ self.assertIn("retention-days: 1", producer)
+ self.assertNotIn("continue-on-error", producer)
+ self.assertNotIn("registry", producer.split("steps:", 1)[0])
+ for job in ("e2e", "agent-registration"):
+ consumer = job_block(workflow, job)
+ self.assertIn("needs: [tier-selection, test-images]", consumer)
+ self.assertIn("PULSE_E2E_SEED_IMAGE: pulse-e2e-seed:test", consumer)
+ self.assertIn("artifact-ids: ${{ needs.test-images.outputs.artifact-id }}", consumer)
+ self.assertIn("PULSE_E2E_MANIFEST_SHA256: ${{ needs.test-images.outputs.manifest-sha256 }}", consumer)
+ self.assertIn('python3 scripts/e2e_test_images.py load "$RUNNER_TEMP/pulse-e2e-images"', consumer)
+ self.assertNotIn("docker build", consumer)
+ self.assertNotIn("docker pull", consumer)
+ self.assertNotIn("github-token:", consumer)
+ self.assertNotIn("repository:", consumer)
+ self.assertNotIn("run-id:", consumer)
+ start = consumer.index("- name: Admit the source-bound test images")
+ end = consumer.index("\n - name:", start + 1)
+ admission = consumer[start:end]
+ for ignored in ("continue-on-error", "if:", "||"):
+ self.assertNotIn(ignored, admission)
+ self.assertLess(start, consumer.index("- name: Start "))
+ self.assertIn("timeout-minutes: 60", job_block(workflow, "e2e"))
+ self.assertIn("shard: [1, 2, 3, 4, 5, 6, 7, 8]", job_block(workflow, "e2e"))
+ self.assertIn("timeout-minutes: 30", job_block(workflow, "agent-registration"))
+ verdict = job_block(workflow, "e2e-verdict")
+ self.assertIn(" - test-images\n", verdict)
+ self.assertIn('if [ "${{ needs.test-images.result }}" != "success" ]; then', verdict)
+ for job in ("tier-selection", "e2e", "agent-registration"):
+ self.assertIn(f'if [ "${{{{ needs.{job}.result }}}}" != "success" ]; then', verdict)
+ self.assertIn("if: always()", verdict)
+
+ def test_workflow_builds_once_and_gates_every_consumer_and_verdict(self):
+ self.assert_workflow(WORKFLOW.read_text())
+
+ def test_proof_and_helper_trigger_and_precede_fanout(self):
+ source = WORKFLOW.read_text()
+ for event in ("pull_request", "push"):
+ block = re.split(r"(?m)^ \S", source.split(f" {event}:\n", 1)[1], maxsplit=1)[0]
+ for file in ("scripts/e2e_test_images.py", "scripts/tests/test_e2e_test_images.py"):
+ self.assertIn(f"'{file}'", block)
+ selection = job_block(source, "tier-selection")
+ self.assertLess(selection.index("python3 scripts/tests/test_e2e_test_images.py"), selection.index("npm ci"))
+
+ def test_rebuild_cross_run_and_ignored_admission_mutants_rejected(self):
+ source = WORKFLOW.read_text()
+ for old, new in (
+ ("needs: [tier-selection, test-images]", "needs: tier-selection"),
+ ("artifact-ids: ${{ needs.test-images.outputs.artifact-id }}", "name: latest-test-images"),
+ ('python3 scripts/e2e_test_images.py load "$RUNNER_TEMP/pulse-e2e-images"', 'docker build -t pulse:test .'),
+ ('python3 scripts/e2e_test_images.py load "$RUNNER_TEMP/pulse-e2e-images"', 'python3 scripts/e2e_test_images.py load "$RUNNER_TEMP/pulse-e2e-images" || true'),
+ ("PULSE_E2E_MANIFEST_SHA256: ${{ needs.test-images.outputs.manifest-sha256 }}", "PULSE_E2E_MANIFEST_SHA256: unchecked"),
+ (" - test-images\n", ""),
+ ):
+ with self.subTest(mutation=new):
+ with self.assertRaises(AssertionError):
+ self.assert_workflow(source.replace(old, new))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/integration/docker-compose.test.yml b/tests/integration/docker-compose.test.yml
index b42e97ac99..c536d6926b 100644
--- a/tests/integration/docker-compose.test.yml
+++ b/tests/integration/docker-compose.test.yml
@@ -2,7 +2,9 @@ services:
# Seed a deterministic bootstrap token for first-run setup E2E flows.
# This is only used by the test stack and is safe to keep deterministic.
seed-bootstrap-token:
- image: alpine:3.24@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6
+ # CI loads this exact seed from its source-bound same-run image bundle.
+ # Local runs keep the pinned registry image.
+ image: ${PULSE_E2E_SEED_IMAGE:-alpine:3.24@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6}
container_name: ${PULSE_E2E_SEED_CONTAINER:-pulse-test-seed-bootstrap-token}
environment:
- PULSE_E2E_BOOTSTRAP_TOKEN=${PULSE_E2E_BOOTSTRAP_TOKEN:-0123456789abcdef0123456789abcdef0123456789abcdef}