Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
39 changes: 39 additions & 0 deletions .github/workflows/validate-publication.yml
Original file line number Diff line number Diff line change
@@ -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
26 changes: 26 additions & 0 deletions deployment/PUBLISHING_POLICY.md
Original file line number Diff line number Diff line change
@@ -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.
76 changes: 76 additions & 0 deletions scripts/build_publication.py
Original file line number Diff line number Diff line change
@@ -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()