diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index cee157c..eac8f54 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -17,6 +17,7 @@ jobs: with: python-version: '3.12' - run: python validate.py + - run: python scripts/build_publication.py deploy: needs: validate runs-on: ubuntu-24.04 @@ -29,9 +30,11 @@ jobs: url: ${{ steps.deploy.outputs.page_url }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + - run: python validate.py + - run: python scripts/build_publication.py - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d - uses: grandchallenge/upload-pages-artifact@4934497e00858680775a65f544192e61e1b1b3cb with: - path: . + path: dist - id: deploy uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 diff --git a/.github/workflows/validate-publication.yml b/.github/workflows/validate-publication.yml new file mode 100644 index 0000000..d08073a --- /dev/null +++ b/.github/workflows/validate-publication.yml @@ -0,0 +1,39 @@ +name: Validate public site candidate +on: + pull_request: + branches: [main] + workflow_dispatch: +permissions: + contents: read +jobs: + publication: + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + with: + persist-credentials: false + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 + with: + python-version: '3.12' + - run: python validate.py + - run: python scripts/build_publication.py + - name: Verify deployed artifact allowlist + shell: bash + run: | + set -euo pipefail + test -f dist/index.html + test -d dist/assets + test ! -e dist/.github + test ! -e dist/deployment + test ! -e dist/scripts + test ! -e dist/CNAME + python - <<'PY' + import json + from pathlib import Path + report = json.loads(Path("publication-manifest.json").read_text()) + assert report["schema"] == "gcl-publication-artifact/1" + assert report["files"] + assert all(p == "index.html" or p.startswith("assets/") for p in report["files"]) + print("PASS: artifact manifest and publication allowlist") + PY diff --git a/deployment/PUBLISHING_POLICY.md b/deployment/PUBLISHING_POLICY.md new file mode 100644 index 0000000..87f3427 --- /dev/null +++ b/deployment/PUBLISHING_POLICY.md @@ -0,0 +1,26 @@ +# Public website release and documentation migration policy + +## Roles and deployment boundaries + +- `grandchallenge/gcl-public-web-preview`: independent design staging at `/gcl-public-web-preview/`; never owns the production domain. +- `grandchallenge/grandchallenge.github.io`: production homepage source; custom domain `grandchallenge.ai` is set in repository Pages settings, not via a checked-in CNAME. +- `grandchallenge/MATH-PROGRAMME`: mathematical documentation and source of authority; its build and deployment remain independent. + +Preview source is **not automatically promoted** to production. For each release, compare the exact preview commit with the current production head; transfer only reviewed changes on a production PR; validate that PR; follow protected merge policy; then check the deployed page and record its final source SHA. Do not copy the preview's Pages settings, workflow, or DNS records. + +## Production artifact + +`python validate.py && python scripts/build_publication.py` validates the homepage and assembles `dist/` containing only `index.html` and `assets/`. `publication-manifest.json` (not deployed) contains SHA-256 hashes for every published file. The workflow publishes `dist/`, never the repository root. No repository metadata, source scripts, or deployment instructions are eligible for upload. + +## Domain cutover acceptance + +1. Verify ownership TXT challenge, apex and www records and GitHub Pages settings. Do not modify MX/SPF email-forwarding records. +2. Check HTTPS and the root site, including redirects from www. +3. Check `/MATH-PROGRAMME/` and the old Pages path independently, including CSS/JS/search assets and mathematical rendering. +4. Reconcile MkDocs `site_url`, canonicals and sitemap only once the actual custom-domain route works. +5. Verify all institutional links and publish a source-revision-bound deployment receipt. +6. Roll back only the root custom-domain assignment/web DNS, if necessary; leave the mathematics source and deploy workflow untouched. + +## MkDocs Material retirement + +Material for MkDocs is in maintenance mode, with upstream critical maintenance through 2027-05-05. Zensical is the preferred migration candidate but must pass parallel builds, generated-documentation hook compatibility, mathematics rendering, search, links, and exact-head publication controls before production switch. Keep the current working generator until evidence supports replacement. diff --git a/scripts/build_publication.py b/scripts/build_publication.py new file mode 100644 index 0000000..ff63a24 --- /dev/null +++ b/scripts/build_publication.py @@ -0,0 +1,76 @@ +"""Assemble the allowlisted GitHub Pages artifact and a source integrity manifest.""" +from __future__ import annotations + +import hashlib +import json +import shutil +from html.parser import HTMLParser +from pathlib import Path +from urllib.parse import urlsplit + +ROOT = Path(__file__).resolve().parents[1] +DIST = ROOT / "dist" + + +class References(HTMLParser): + def __init__(self): + super().__init__() + self.paths = set() + + def handle_starttag(self, tag, attrs): + attributes = dict(attrs) + for name in ("src", "href"): + value = attributes.get(name, "") + if not value or value.startswith(("#", "/", "//")): + continue + split = urlsplit(value) + if split.scheme or split.netloc or not split.path: + continue + path = Path(split.path) + if path.is_absolute() or ".." in path.parts: + raise SystemExit(f"unsafe local reference: {value}") + self.paths.add(path) + + +def main() -> None: + index = ROOT / "index.html" + if not index.is_file(): + raise SystemExit("missing homepage") + parser = References() + parser.feed(index.read_text(encoding="utf-8")) + # The public site consists only of index.html and assets/. Nothing else + # from the checkout is eligible for publication. + for path in parser.paths: + if not path.parts or path.parts[0] != "assets": + raise SystemExit(f"unexpected local website dependency: {path}") + resolved = (ROOT / path).resolve() + if not resolved.is_file() or not resolved.is_relative_to((ROOT / "assets").resolve()): + raise SystemExit(f"missing/unsafe website dependency: {path}") + if not (ROOT / "assets").is_dir(): + raise SystemExit("missing assets directory") + for asset in (ROOT / "assets").rglob("*"): + if asset.is_symlink(): + raise SystemExit(f"symlink not allowed in public assets: {asset}") + if DIST.exists(): + shutil.rmtree(DIST) + DIST.mkdir() + shutil.copy2(index, DIST / "index.html") + shutil.copytree(ROOT / "assets", DIST / "assets", symlinks=False) + if (DIST / "CNAME").exists(): + raise SystemExit("custom domains are configured in Pages settings, not this artifact") + manifest = { + "schema": "gcl-publication-artifact/1", + "files": { + str(p.relative_to(DIST)): hashlib.sha256(p.read_bytes()).hexdigest() + for p in sorted(DIST.rglob("*")) if p.is_file() + }, + } + # Store the manifest outside the published artifact. + (ROOT / "publication-manifest.json").write_text( + json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8" + ) + print(f"PASS: {len(manifest['files'])} public files, all local references resolved") + + +if __name__ == "__main__": + main()