ci: record Fern publish provenance

Author: andreatgretel

.github/workflows/build-fern-docs.yml

@@ -114,10 +114,19 @@ jobs:
       - name: Prepare Fern release snapshot
         env:
           RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
+          SOURCE_REF: ${{ needs.resolve-release.outputs.source_ref }}
+          SOURCE_REPOSITORY: ${{ github.repository }}
+          PUBLISHED_BRANCH: ${{ env.FERN_PUBLISHED_BRANCH }}
         run: |
+          source_sha=$(git -C source rev-parse HEAD)
           python3 workflow/fern/scripts/fern-published-branch.py sync-source \
             --source-root source \
-            --published-root website
+            --published-root website \
+            --metadata-source-repository "$SOURCE_REPOSITORY" \
+            --metadata-source-ref "$SOURCE_REF" \
+            --metadata-source-sha "$source_sha" \
+            --metadata-release-tag "$RELEASE_TAG" \
+            --metadata-published-branch "$PUBLISHED_BRANCH"
           python3 workflow/fern/scripts/fern-release-version.py --root website/fern prepare --version "$RELEASE_TAG" --force
           python3 workflow/fern/scripts/fern-release-version.py --root website/fern check --version "$RELEASE_TAG" --require-latest-matches-release
 
@@ -146,17 +155,24 @@ jobs:
       - name: Commit published branch
         env:
           RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
+          SOURCE_REF: ${{ needs.resolve-release.outputs.source_ref }}
+          SOURCE_REPOSITORY: ${{ github.repository }}
         working-directory: website
         run: |
           if [ -z "$(git status --porcelain)" ]; then
             echo "::notice::Fern published branch already has $RELEASE_TAG."
             exit 0
           fi
 
+          source_sha=$(git -C ../source rev-parse HEAD)
+          previous_published_sha=$(git rev-parse HEAD)
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add -A
-          git commit -m "docs: publish Fern docs for $RELEASE_TAG"
+          git commit \
+            -m "docs: publish Fern docs for $RELEASE_TAG" \
+            -m "Source: $SOURCE_REPOSITORY@$SOURCE_REF ($source_sha)" \
+            -m "Previous docs-website head: $previous_published_sha"
           git push origin HEAD:"$FERN_PUBLISHED_BRANCH"
 
   build-notebooks:

.github/workflows/publish-fern-devnotes.yml

@@ -65,10 +65,19 @@ jobs:
           git checkout -B "$FERN_PUBLISHED_BRANCH" FETCH_HEAD
 
       - name: Patch Dev Notes into latest Fern docs
+        env:
+          SOURCE_REF: ${{ github.ref }}
+          SOURCE_REPOSITORY: ${{ github.repository }}
+          PUBLISHED_BRANCH: ${{ env.FERN_PUBLISHED_BRANCH }}
         run: |
+          source_sha=$(git -C source rev-parse HEAD)
           python3 workflow/fern/scripts/fern-published-branch.py patch-devnotes \
             --source-root source \
-            --published-root website
+            --published-root website \
+            --metadata-source-repository "$SOURCE_REPOSITORY" \
+            --metadata-source-ref "$SOURCE_REF" \
+            --metadata-source-sha "$source_sha" \
+            --metadata-published-branch "$PUBLISHED_BRANCH"
 
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
@@ -115,17 +124,25 @@ jobs:
         run: make check-fern-docs
 
       - name: Commit published branch
+        env:
+          SOURCE_REF: ${{ github.ref }}
+          SOURCE_REPOSITORY: ${{ github.repository }}
         working-directory: website
         run: |
           if [ -z "$(git status --porcelain)" ]; then
             echo "::notice::Fern Dev Notes are already up to date."
             exit 0
           fi
 
+          source_sha=$(git -C ../source rev-parse HEAD)
+          previous_published_sha=$(git rev-parse HEAD)
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add -A
-          git commit -m "docs: patch Fern devnotes into latest"
+          git commit \
+            -m "docs: patch Fern devnotes into latest" \
+            -m "Source: $SOURCE_REPOSITORY@$SOURCE_REF ($source_sha)" \
+            -m "Previous docs-website head: $previous_published_sha"
           git push origin HEAD:"$FERN_PUBLISHED_BRANCH"
 
       - name: Publish Fern docs

fern/AGENTS.md

@@ -24,6 +24,8 @@ This folder contains the Fern docs site for NeMo Data Designer. Use `fern/README
 
 Published release snapshots live on the CI-managed `docs-website` branch. Do not manually edit `docs-website` unless the user explicitly asks for release archive repair.
 
+`docs-website` is an orphan-style publish branch. Published commits should include `fern/publish-metadata.json` with source repository, ref, SHA, release tag when applicable, and published branch.
+
 The `docs-website` branch must already contain the historical Fern archive (`v0.6.0`, `v0.5.9`, `v0.5.8`, and `older`). The release workflow fails if those redirect targets are missing.
 
 Frozen `vX.Y.Z.yml` navs on `docs-website` must point only at their own `vX.Y.Z/pages/...` files. The release sync materializes shared historical pages into each version folder before publishing.

fern/README.md

@@ -71,6 +71,8 @@ These workflows require the org-level `DOCS_FERN_TOKEN` secret. The workflows ex
 
 Fern release snapshots live on `docs-website`, not on `main`. This mirrors the MkDocs `gh-pages` model without mixing Fern source state into the MkDocs output branch. The branch stores a source snapshot, not only `fern/`, because `make check-fern-docs` needs the Python packages and workspace metadata. Pushes to `docs-website` use `GITHUB_TOKEN`, so publishing happens inline in the same workflow instead of relying on a second workflow trigger.
 
+The `docs-website` branch is an orphan-style publish branch. Published commits include `fern/publish-metadata.json` with the source repository, ref, SHA, release tag when applicable, and published branch.
+
 The `docs-website` branch must already contain the historical Fern archive (`v0.6.0`, `v0.5.9`, `v0.5.8`, and `older`) before release publishing runs. The workflow fails if those redirect targets are missing.
 
 Manual dispatch with `release_tag` creates or refreshes that release snapshot. For the already-published `v0.6.0` release, run **Build Fern docs** with `release_tag=v0.6.0` and `source_ref=main` after this fix merges. Future release events default `source_ref` to the release tag.

fern/scripts/fern-published-branch.py

@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import re
 import shutil
 import sys
@@ -31,6 +32,7 @@
     "dist",
     "site",
 }
+PUBLISH_METADATA_PATH = Path("fern/publish-metadata.json")
 FERN_DEVNOTE_SUPPORT_PATHS = [
     "fern/assets",
     "fern/components/Authors.tsx",
@@ -166,6 +168,49 @@ def validate_redirect_targets(published_root: Path) -> None:
         )
 
 
+def write_publish_metadata(published_root: Path, args: argparse.Namespace, action: str) -> None:
+    provided = [
+        args.metadata_source_repository,
+        args.metadata_source_ref,
+        args.metadata_source_sha,
+        args.metadata_release_tag,
+        args.metadata_published_branch,
+    ]
+    if not any(provided):
+        return
+
+    missing = [
+        name
+        for name, value in (
+            ("metadata source repository", args.metadata_source_repository),
+            ("metadata source ref", args.metadata_source_ref),
+            ("metadata source sha", args.metadata_source_sha),
+        )
+        if not value
+    ]
+    if missing:
+        raise PublishedBranchError(f"Incomplete publish metadata; missing {', '.join(missing)}")
+
+    metadata: dict[str, object] = {
+        "schema_version": 1,
+        "kind": "fern-docs-website",
+        "action": action,
+        "source": {
+            "repository": args.metadata_source_repository,
+            "ref": args.metadata_source_ref,
+            "sha": args.metadata_source_sha,
+        },
+    }
+    if args.metadata_release_tag:
+        metadata["release_tag"] = args.metadata_release_tag
+    if args.metadata_published_branch:
+        metadata["published_branch"] = args.metadata_published_branch
+
+    target = published_root / PUBLISH_METADATA_PATH
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(metadata, indent=2) + "\n")
+
+
 def ignore_source(_dir: str, names: list[str]) -> set[str]:
     return {name for name in names if name in SKIP_NAMES or name == "__pycache__"}
 
@@ -347,6 +392,7 @@ def sync_source(args: argparse.Namespace) -> int:
         materialize_version_nav_pages(published_root)
         restore_versions_block(published_root / "fern" / "docs.yml", preserved_versions_block)
         validate_redirect_targets(published_root)
+        write_publish_metadata(published_root, args, "release-snapshot")
     return 0
 
 
@@ -396,21 +442,32 @@ def patch_devnotes(args: argparse.Namespace) -> int:
 
     source_block = extract_devnotes_block(source_nav)
     replace_devnotes_block(target_nav, rewrite_devnotes_block(source_root, published_root, source_block))
+    write_publish_metadata(published_root, args, "devnotes-patch")
     return 0
 
 
+def add_metadata_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--metadata-source-repository", help="Repository used to produce this published snapshot")
+    parser.add_argument("--metadata-source-ref", help="Git ref used to produce this published snapshot")
+    parser.add_argument("--metadata-source-sha", help="Git commit used to produce this published snapshot")
+    parser.add_argument("--metadata-release-tag", help="Release tag represented by this published snapshot")
+    parser.add_argument("--metadata-published-branch", help="Published branch updated by this snapshot")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__)
     subparsers = parser.add_subparsers(required=True)
 
     sync_parser = subparsers.add_parser("sync-source")
     sync_parser.add_argument("--source-root", required=True, help="Repository checkout with authoring content")
     sync_parser.add_argument("--published-root", required=True, help="docs-website checkout to update")
+    add_metadata_args(sync_parser)
     sync_parser.set_defaults(func=sync_source)
 
     devnotes_parser = subparsers.add_parser("patch-devnotes")
     devnotes_parser.add_argument("--source-root", required=True, help="Repository checkout with latest Dev Notes")
     devnotes_parser.add_argument("--published-root", required=True, help="docs-website checkout to patch")
+    add_metadata_args(devnotes_parser)
     devnotes_parser.set_defaults(func=patch_devnotes)
     return parser