Merge pull request #143 from lsst-sqre/tickets/DM-54492

DM-54492: Edition updates and tracking

Author: jonathansick

alembic/versions/20260327_0000_g5h6i7j8k9l0_add_edition_build_history.py

@@ -0,0 +1,57 @@
+"""Add edition_build_history table.
+
+Logs every build that an edition has pointed to, enabling rollback
+and orphan detection.
+
+Revision ID: g5h6i7j8k9l0
+Revises: f4a5b6c7d8e9
+Create Date: 2026-03-27 00:00:00.000000+00:00
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "g5h6i7j8k9l0"
+down_revision: str | None = "f4a5b6c7d8e9"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "edition_build_history",
+        sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+        sa.Column(
+            "edition_id",
+            sa.Integer,
+            sa.ForeignKey("editions.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "build_id",
+            sa.Integer,
+            sa.ForeignKey("builds.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("position", sa.Integer, nullable=False),
+        sa.Column(
+            "date_created",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index(
+        "idx_ebh_edition_id", "edition_build_history", ["edition_id"]
+    )
+    op.create_index(
+        "idx_ebh_edition_position",
+        "edition_build_history",
+        ["edition_id", "position"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("edition_build_history")

alembic/versions/20260327_0001_h6i7j8k9l0m1_add_org_default_edition_config.py

@@ -0,0 +1,31 @@
+"""Add default_edition_config column to organizations.
+
+Stores the organization-level default tracking configuration for
+the __main edition created on new projects.
+
+Revision ID: h6i7j8k9l0m1
+Revises: g5h6i7j8k9l0
+Create Date: 2026-03-27 00:01:00.000000+00:00
+"""
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "h6i7j8k9l0m1"
+down_revision: str | None = "g5h6i7j8k9l0"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "organizations",
+        sa.Column("default_edition_config", JSONB, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("organizations", "default_edition_config")

client/src/docverse/client/_annotations.py

@@ -0,0 +1,63 @@
+"""Auto-detection of build provenance annotations from CI environments."""
+
+from __future__ import annotations
+
+import os
+
+from .models.builds import BuildAnnotations
+
+__all__ = [
+    "detect_github_actions_annotations",
+    "merge_annotations",
+]
+
+
+def detect_github_actions_annotations() -> BuildAnnotations | None:
+    """Detect build provenance from GitHub Actions environment variables.
+
+    Returns a populated ``BuildAnnotations`` if running inside GitHub
+    Actions (``GITHUB_ACTIONS == "true"``), otherwise ``None``.
+    """
+    if os.environ.get("GITHUB_ACTIONS") != "true":
+        return None
+
+    server_url = os.environ.get("GITHUB_SERVER_URL", "https://github.com")
+    repository = os.environ.get("GITHUB_REPOSITORY")
+    run_id = os.environ.get("GITHUB_RUN_ID")
+
+    run_url: str | None = None
+    if repository and run_id:
+        run_url = f"{server_url}/{repository}/actions/runs/{run_id}"
+
+    return BuildAnnotations(
+        commit_sha=os.environ.get("GITHUB_SHA"),
+        github_repository=repository,
+        github_run_id=run_id,
+        github_run_url=run_url,
+        github_run_attempt=os.environ.get("GITHUB_RUN_ATTEMPT"),
+        github_workflow=os.environ.get("GITHUB_WORKFLOW"),
+        github_actor=os.environ.get("GITHUB_ACTOR"),
+        github_event_name=os.environ.get("GITHUB_EVENT_NAME"),
+        ci_platform="github-actions",
+    )
+
+
+def merge_annotations(
+    auto: BuildAnnotations | None,
+    manual: dict[str, str] | None,
+) -> BuildAnnotations | None:
+    """Merge auto-detected and manual annotations.
+
+    Manual entries take precedence over auto-detected values.  Returns
+    ``None`` if both inputs are empty/None.
+    """
+    result: dict[str, str] = {}
+    if auto is not None:
+        result.update(
+            {k: v for k, v in auto.model_dump().items() if v is not None}
+        )
+    if manual:
+        result.update(manual)
+    if not result:
+        return None
+    return BuildAnnotations.model_validate(result)

client/src/docverse/client/_cli.py

@@ -9,6 +9,7 @@
 
 import click
 
+from ._annotations import detect_github_actions_annotations, merge_annotations
 from ._client import DocverseClient
 from ._exceptions import BuildProcessingError, DocverseClientError
 from ._tar import create_tarball
@@ -76,6 +77,19 @@ def main() -> None:
     default=None,
     help="Alternate deployment name.",
 )
+@click.option(
+    "--annotation",
+    "-a",
+    "annotations",
+    multiple=True,
+    help="Manual annotation in KEY=VALUE format. Can be repeated.",
+)
+@click.option(
+    "--auto-annotations/--no-auto-annotations",
+    default=True,
+    show_default=True,
+    help="Auto-detect annotations from CI environment variables.",
+)
 @click.option(
     "--no-wait",
     is_flag=True,
@@ -97,12 +111,26 @@ def upload(  # noqa: PLR0913
     token: str,
     base_url: str,
     alternate_name: str | None,
+    annotations: tuple[str, ...],
+    auto_annotations: bool,  # noqa: FBT001
     no_wait: bool,  # noqa: FBT001
     verbose: bool,  # noqa: FBT001
 ) -> None:
     """Upload a documentation build."""
     if git_ref is None:
         git_ref = _detect_git_ref()
+
+    # Parse manual annotations
+    manual: dict[str, str] | None = None
+    if annotations:
+        manual = {}
+        for item in annotations:
+            if "=" not in item:
+                msg = f"Invalid annotation format (expected KEY=VALUE): {item}"
+                raise click.BadParameter(msg, param_hint="'--annotation'")
+            key, value = item.split("=", 1)
+            manual[key] = value
+
     asyncio.run(
         _upload_async(
             org=org,
@@ -112,6 +140,8 @@ def upload(  # noqa: PLR0913
             token=token,
             base_url=base_url,
             alternate_name=alternate_name,
+            auto_annotations=auto_annotations,
+            manual_annotations=manual,
             no_wait=no_wait,
             verbose=verbose,
         )
@@ -145,6 +175,8 @@ async def _upload_async(  # noqa: PLR0913
     token: str,
     base_url: str,
     alternate_name: str | None,
+    auto_annotations: bool,
+    manual_annotations: dict[str, str] | None,
     no_wait: bool,
     verbose: bool,
 ) -> None:
@@ -155,6 +187,12 @@ async def _upload_async(  # noqa: PLR0913
         tarball_path, content_hash = create_tarball(source_dir)
         click.echo(f"Content hash: {content_hash}")
 
+        # Build annotations from auto-detection and manual entries
+        auto = (
+            detect_github_actions_annotations() if auto_annotations else None
+        )
+        merged_annotations = merge_annotations(auto, manual_annotations)
+
         async with DocverseClient(base_url, token, verbose=verbose) as client:
             click.echo(f"Creating build for {org}/{project} @ {git_ref}")
             build = await client.create_build(
@@ -163,6 +201,7 @@ async def _upload_async(  # noqa: PLR0913
                 git_ref=git_ref,
                 content_hash=content_hash,
                 alternate_name=alternate_name,
+                annotations=merged_annotations,
             )
             click.echo(f"Build created: {build.id}")
 

client/src/docverse/client/_client.py

@@ -12,6 +12,7 @@
 
 from ._exceptions import BuildProcessingError, DocverseClientError
 from .models import Build, BuildStatus, BuildUpdate, QueueJob
+from .models.builds import BuildAnnotations
 from .models.queue_enums import JobStatus
 
 __all__ = ["DocverseClient"]
@@ -130,7 +131,7 @@ async def create_build(  # noqa: PLR0913
         git_ref: str,
         content_hash: str,
         alternate_name: str | None = None,
-        annotations: dict[str, Any] | None = None,
+        annotations: BuildAnnotations | None = None,
     ) -> Build:
         """Create a new build.
 
@@ -161,7 +162,7 @@ async def create_build(  # noqa: PLR0913
         if alternate_name is not None:
             payload["alternate_name"] = alternate_name
         if annotations is not None:
-            payload["annotations"] = annotations
+            payload["annotations"] = annotations.model_dump(exclude_none=True)
 
         url = f"/orgs/{org}/projects/{project}/builds"
         response = await self._client.post(url, json=payload)

client/src/docverse/client/models/__init__.py

@@ -1,6 +1,12 @@
 """Pydantic models for the Docverse API."""
 
-from .builds import Build, BuildCreate, BuildStatus, BuildUpdate
+from .builds import (
+    Build,
+    BuildAnnotations,
+    BuildCreate,
+    BuildStatus,
+    BuildUpdate,
+)
 from .credentials import (
     AwsCredentials,
     CloudflareCredentials,
@@ -12,9 +18,12 @@
     S3Credentials,
 )
 from .editions import (
+    DefaultEditionConfig,
     Edition,
+    EditionBuildHistoryEntry,
     EditionCreate,
     EditionKind,
+    EditionRollback,
     EditionUpdate,
     TrackingMode,
 )
@@ -49,15 +58,19 @@
 __all__ = [
     "AwsCredentials",
     "Build",
+    "BuildAnnotations",
     "BuildCreate",
     "BuildStatus",
     "BuildUpdate",
     "CloudflareCredentials",
     "CredentialPayload",
     "CredentialProvider",
+    "DefaultEditionConfig",
     "Edition",
+    "EditionBuildHistoryEntry",
     "EditionCreate",
     "EditionKind",
+    "EditionRollback",
     "EditionUpdate",
     "FastlyCredentials",
     "GcpCredentials",