Add CI check for breaking changes to util-genai public API

.github/instructions/util-genai.instructions.md

@@ -37,6 +37,9 @@ land the semconv change first.
 
 - Do not remove or rename public objects. Deprecate first via a docstring note pointing to the
   replacement (not `@deprecated` — unreliable).
+- The `check-util-api` CI job fails when a public object is removed or its signature changes
+  compared to main. When a PR does this on purpose, ask it to list which released
+  instrumentations it checked, in this repo and in opentelemetry-python-contrib.
 - Private modules and module-private objects start with `_`.
 - Default to internal (`_`-prefixed) unless instrumentations need it public.
 - Flag every `Any` in the public API (anything not under a `_`-prefixed module) — parameters,

.github/workflows/misc.yml

@@ -194,6 +194,32 @@ jobs:
       - name: Run dependency check
         run: uv run --with packaging scripts/check_deps.py
 
+  check-util-api:
+    name: check-util-api
+    runs-on: ubuntu-slim
+    timeout-minutes: 10
+    if: |
+      !contains(github.event.pull_request.labels.*.name, 'Approve Public API check')
+      && github.event.pull_request.user.login != 'otelbot[bot]' && github.event_name == 'pull_request'
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          # griffe needs the PR base branch available for comparison.
+          fetch-depth: 0
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      - name: Check util public API
+        run: uvx --with tox-uv tox -e check-util-api
+
   license-header-check:
     name: license-header-check
     runs-on: ubuntu-slim

AGENTS.md

@@ -127,12 +127,20 @@ uv run tox -e py314-test-instrumentation-genai-openai-conformance
 
 # Type check (pyright)
 uv run tox -e typecheck
+
+# Check util-genai for public API breaks against main
+uv run tox -e check-util-api
 ```
 
 Before opening a PR, run `uv run tox -e precommit`, `uv run tox -e typecheck`, and the changed package's
 test envs (`-oldest` and `-latest`, plus `-conformance` if it ships scenarios) — these mirror
 the CI gates.
 
+If you change `util/opentelemetry-util-genai`, also run `uv run tox -e check-util-api`. Released
+instrumentations accept any util version below 2, so removing or changing a public object can
+break them on import. If the break is intended, say in the PR which released instrumentations you
+checked. A maintainer then adds the `Approve Public API check` label to skip the CI job.
+
 tox reuses cached envs and won't re-resolve dependencies on its own, so pass `--recreate` (`-r`)
 after editing a `tests/requirements.*.txt` or a `pyproject.toml` dependency bound — otherwise the
 run silently uses the previously installed versions.

dev-requirements.txt

@@ -8,5 +8,6 @@ readme-renderer==46.0
 bleach==6.4.0 # transient dependency for readme-renderer
 markupsafe>=3.0.4
 codespell==2.4.3
+griffe==2.3.0
 pre-commit==4.6.2
 ruff==0.16.10

tox.ini

@@ -384,6 +384,13 @@ deps =
 commands =
   python {toxinidir}/scripts/check_deps.py
 
+[testenv:check-util-api]
+description = Fail on breaking changes to the opentelemetry-util-genai public API vs the PR base branch (main locally).
+deps =
+  -c {toxinidir}/dev-requirements.txt
+  griffe
+commands =
+  griffe check opentelemetry.util.genai -s util/opentelemetry-util-genai/src -a origin/{env:GITHUB_BASE_REF:main}
 
 [testenv:changelog-preview]
 description = Render a draft changelog for every package that uses towncrier.