ci(gapic-generator): add showcase canary job, span artifact upload, and isolate goldens from pre-commit (#18518)

### Problem
1. Pre-commit hooks run across the whole monorepo and risk reformatting
or modifying Bazel integration test golden files
(`packages/gapic-generator/tests/integration/goldens/`), causing false
positive diff failures in golden verification tests.
2. In monorepo CI, gapic-generator integration tests install
dependencies from PyPI rather than testing directly against local,
unpublished changes in sibling packages like `google-api-core`. Being
able to run showcase tests against local changes is critical for ongoing
work such as the observability work.
3. When running system tests in CI, there is currently no mechanism to
preserve and download raw output data (such as telemetry span dumps) to
debug result regressions or verify compliance artifacts.

### Solution
- Exclude `packages/gapic-generator/tests/integration/goldens/` from
`.pre-commit-config.yaml` to ensure golden files remain untouched by
repository-wide hooks.
- Add `showcase-canary` job to
`.github/workflows/gapic-generator-tests.yml` that runs Showcase
integration tests against the local monorepo `google-api-core` when
`INSTALL_LOCAL_CORE="true"`.
- Support the `INSTALL_LOCAL_CORE` environment variable in
`packages/gapic-generator/noxfile.py` to optionally install local core
in development and CI environments.
- Add an `Upload Raw Spans Artifact` step to both `showcase` and
`showcase-canary` jobs to upload `raw_spans_output.json` as a build
artifact.

### Notes for Reviewers
- This change is strictly focused on testing infrastructure and
repository hygiene.
- It does not modify any client generation code or generator templates.

Author: chalmerlowe

.github/workflows/gapic-generator-tests.yml

@@ -71,7 +71,7 @@ jobs:
         with:
           python-version: "${{ matrix.python }}"
           allow-prereleases: true
-          # Caches compiled wheels locally to prevent building heavy libraries 
+          # Caches compiled wheels locally to prevent building heavy libraries
           # such as grpcio, which we build from scratch on every run for Python 3.15+.
           # Follow https://github.com/grpc/grpc/issues/41010 for updates.
           cache: 'pip'
@@ -142,6 +142,68 @@ jobs:
           run: |
             cd packages/gapic-generator
             nox -s ${{ matrix.target }}-${MATRIX_PYTHON}
+        - name: Upload Raw Spans Artifact
+          if: always()
+          uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+          with:
+            name: raw-spans-${{ matrix.target }}-${{ matrix.python }}${{ matrix.logging_scope && format('-{0}', matrix.logging_scope) || '' }}
+            path: packages/gapic-generator/tests/system/raw_spans_output.json
+            if-no-files-found: ignore
+
+  showcase-canary:
+      needs: python_config
+      strategy:
+        # Run canary tests with local monorepo google-api-core on bookend runtimes
+        matrix:
+          python: ["${{ needs.python_config.outputs.oldest_python }}", "${{ needs.python_config.outputs.latest_stable_python }}"]
+          target: [showcase, showcase_w_rest_async]
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+          with:
+            persist-credentials: false
+        - name: Set up Python "${{ matrix.python }}"
+          uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+          with:
+            python-version: "${{ matrix.python }}"
+            cache: 'pip'
+        - name: Install system dependencies.
+          run: |
+            sudo apt-get update
+            sudo apt-get install -y curl pandoc unzip
+        - name: Install showcase
+          run: |
+            sudo mkdir -p /usr/src/showcase
+            sudo chown -R ${USER} /usr/src/
+            curl --location https://github.com/googleapis/gapic-showcase/releases/download/v${SHOWCASE_VERSION}/gapic-showcase-${SHOWCASE_VERSION}-linux-amd64.tar.gz --output /usr/src/showcase/showcase-${SHOWCASE_VERSION}-linux-amd64.tar.gz
+            cd /usr/src/showcase/
+            tar -xf showcase-*
+            ./gapic-showcase run &
+            cd -
+        - name: Install nox.
+          run: python -m pip install nox
+        - name: Install protoc
+          run: |
+              sudo mkdir -p /usr/src/protoc/
+              sudo chown -R ${USER} /usr/src/
+              curl --location https://github.com/google/protobuf/releases/download/v${PROTOC_VERSION}/protoc-${PROTOC_VERSION}-linux-x86_64.zip --output /usr/src/protoc/protoc-${PROTOC_VERSION}.zip
+              cd /usr/src/protoc/
+              unzip protoc-${PROTOC_VERSION}.zip
+              sudo ln -s /usr/src/protoc/bin/protoc /usr/local/bin/protoc
+        - name: Run showcase canary with local google-api-core.
+          env:
+            INSTALL_LOCAL_CORE: "true"
+            MATRIX_PYTHON: ${{ matrix.python }}
+          run: |
+            cd packages/gapic-generator
+            nox -s ${{ matrix.target }}-${MATRIX_PYTHON}
+        - name: Upload Raw Spans Artifact
+          if: always()
+          uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+          with:
+            name: raw-spans-canary-${{ matrix.target }}-${{ matrix.python }}
+            path: packages/gapic-generator/tests/system/raw_spans_output.json
+            if-no-files-found: ignore
 
   showcase-mypy:
     needs: python_config
@@ -210,7 +272,7 @@ jobs:
         with:
           python-version: ${{ needs.python_config.outputs.prerelease_python }}
           allow-prereleases: true
-          # Caches compiled wheels locally to prevent building heavy libraries 
+          # Caches compiled wheels locally to prevent building heavy libraries
           # such as grpcio, which we build from scratch on every run for Python 3.15+.
           # Follow https://github.com/grpc/grpc/issues/41010 for updates.
           cache: 'pip'
@@ -242,7 +304,7 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
           allow-prereleases: true
-          # Caches compiled wheels locally to prevent building heavy libraries 
+          # Caches compiled wheels locally to prevent building heavy libraries
           # such as grpcio, which we build from scratch on every run for Python 3.15+.
           # Follow https://github.com/grpc/grpc/issues/41010 for updates.
           cache: 'pip'
@@ -287,13 +349,13 @@ jobs:
 
       - name: Run Bazel Integration Tests
         run: |
-          # We need to move into the package directory if the 
+          # We need to move into the package directory if the
           # WORKSPACE file is located there.
           cd packages/gapic-generator
           bazelisk test //tests/integration/... --test_output=errors
 
   # Final job to simplify branch protection rules.
-  # This job will be reported as 'Success' if all its dependencies either 
+  # This job will be reported as 'Success' if all its dependencies either
   # pass or are skipped due to path filtering.
   status:
     needs: [check_changes, python_config, showcase-unit, showcase, showcase-mypy, goldens, goldens-prerelease, fragment-snippet, integration]
@@ -314,4 +376,3 @@ jobs:
             exit 1
           fi
           echo "All checks passed or were successfully skipped."
-

.pre-commit-config.yaml

@@ -14,6 +14,7 @@
 #
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
+exclude: '^packages/gapic-generator/tests/integration/goldens/'
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0

packages/gapic-generator/docs/conf.py

@@ -183,4 +183,16 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/3/": None}
+intersphinx_mapping = {}
+
+# Check reachability of the Python standard library inventory before attaching it.
+# Because Sphinx is run with `-W` (warnings as errors) in CI, an external network
+# failure or upstream outage on docs.python.org would otherwise treat the missing
+# inventory as a fatal error and fail the build.
+try:
+    import urllib.request
+
+    with urllib.request.urlopen("https://docs.python.org/3/objects.inv", timeout=2):
+        intersphinx_mapping["https://docs.python.org/3/"] = None
+except Exception:
+    pass

packages/gapic-generator/noxfile.py

@@ -18,18 +18,18 @@
 #   PIP_INDEX_URL=https://pypi.org/simple nox
 
 from __future__ import absolute_import
-from concurrent.futures import ThreadPoolExecutor
-from pathlib import Path
+
 import os
+import shutil
 import sys
 import tempfile
 import typing
-import nox  # type: ignore
-
+from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
 from os import path
-import shutil
+from pathlib import Path
 
+import nox  # type: ignore
 
 nox.options.error_on_missing_interpreters = True
 
@@ -401,9 +401,23 @@ def showcase(
     other_opts: typing.Iterable[str] = (),
     env: typing.Optional[typing.Dict[str, str]] = {},
 ):
-    """Run the Showcase test suite."""
+    """Run the Showcase test suite.
+
+    Set INSTALL_LOCAL_CORE=true to install packages/google-api-core from source
+    (useful for local testing and canary validation).
+    """
 
     with showcase_library(session, templates=templates, other_opts=other_opts):
+        # When opt-in environment variable is set (e.g. in canary CI or local testing),
+        # install the local google-api-core package from source.
+        if os.getenv("INSTALL_LOCAL_CORE") == "true":
+            local_core = Path(__file__).resolve().parent.parent / "google-api-core"
+            if not local_core.is_dir():
+                session.error(
+                    f"INSTALL_LOCAL_CORE is set to 'true' but {local_core} does not exist."
+                )
+            session.install("-e", str(local_core))
+
         # Use pytest-asyncio<1.0.0 while we investigate the recent failure described in
         # https://github.com/googleapis/gapic-generator-python/issues/2399
         session.install("pytest", "pytest-asyncio<1.0.0")
@@ -431,11 +445,25 @@ def showcase_w_rest_async(
     other_opts: typing.Iterable[str] = (),
     env: typing.Optional[typing.Dict[str, str]] = {},
 ):
-    """Run the Showcase test suite."""
+    """Run the Showcase test suite with async rest transport.
+
+    Set INSTALL_LOCAL_CORE=true to install packages/google-api-core from source
+    (useful for local testing and canary validation).
+    """
 
     with showcase_library(
         session, templates=templates, other_opts=other_opts, rest_async_io_enabled=True
     ):
+        # When opt-in environment variable is set (e.g. in canary CI or local testing),
+        # install the local google-api-core package from source.
+        if os.getenv("INSTALL_LOCAL_CORE") == "true":
+            local_core = Path(__file__).resolve().parent.parent / "google-api-core"
+            if not local_core.is_dir():
+                session.error(
+                    f"INSTALL_LOCAL_CORE is set to 'true' but {local_core} does not exist."
+                )
+            session.install("-e", str(local_core))
+
         # Use pytest-asyncio<1.0.0 while we investigate the recent failure described in
         # https://github.com/googleapis/gapic-generator-python/issues/2399
         session.install("pytest", "pytest-asyncio<1.0.0")
@@ -498,7 +526,13 @@ def showcase_pqc(
     with showcase_library(session, templates=templates, other_opts=other_opts):
         session.install("pytest", "pytest-asyncio")
         session.install("--upgrade", "grpcio>=1.83.0", "grpcio-status>=1.83.0")
-        session.run("py.test", "--quiet", "--tls", *(session.posargs or ["tests/system/test_pqc.py"]), env=env)
+        session.run(
+            "py.test",
+            "--quiet",
+            "--tls",
+            *(session.posargs or ["tests/system/test_pqc.py"]),
+            env=env,
+        )
 
 
 def run_showcase_unit_tests(session, fail_under=100, rest_async_io_enabled=False):