Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(release): attach a labelled openapi.json to every GitHub release (#3948)

Raghav Chamadiyaca5263f66034
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 7985cdb75..82a50aa1b 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -85,6 +85,34 @@ jobs:
name: dist
path: dist/
+ # ---------------------------------------------------------------------------
+ # Export the server's OpenAPI document, labelled stable or internal per route
+ # ---------------------------------------------------------------------------
+ build-openapi:
+ name: Export OpenAPI document
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v3
+ with:
+ version: "latest"
+ enable-cache: true
+
+ - name: Install dependencies
+ run: uv sync --all-packages
+
+ - name: Export openapi.json
+ run: uv run python scripts/export_openapi.py --out openapi.json
+
+ - name: Upload OpenAPI artifact
+ uses: actions/upload-artifact@v4
+ with:
+ name: openapi
+ path: openapi.json
+
# ---------------------------------------------------------------------------
# Create GitHub release with web UI tarball
# ---------------------------------------------------------------------------
@@ -114,6 +142,27 @@ jobs:
dist/*
generate_release_notes: true
+ # ---------------------------------------------------------------------------
+ # Attach openapi.json after the release exists, so a failed export never
+ # holds back the web tarball that `repowise serve` downloads
+ # ---------------------------------------------------------------------------
+ attach-openapi:
+ name: Attach OpenAPI document
+ needs: [release, build-openapi]
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Download OpenAPI document
+ uses: actions/download-artifact@v4
+ with:
+ name: openapi
+ path: ./openapi/
+
+ - name: Attach to release
+ uses: softprops/action-gh-release@v2
+ with:
+ files: openapi/openapi.json
+
# ---------------------------------------------------------------------------
# Publish to PyPI
# ---------------------------------------------------------------------------
diff --git a/docs/reference/API_REFERENCE.md b/docs/reference/API_REFERENCE.md
index 1fa7093b9..c81caa287 100644
--- a/docs/reference/API_REFERENCE.md
+++ b/docs/reference/API_REFERENCE.md
@@ -11,6 +11,12 @@ how authentication behaves, the shape of an error, how the two SSE streams are
sequenced, and the conventions several routes share. Start at `/docs` for a
specific endpoint; come back here for the things a schema cannot state.
+Each GitHub release also carries the same document as an `openapi.json` asset
+(`https://github.com/repowise-dev/repowise/releases/latest/download/openapi.json`).
+Every operation in it has `x-repowise-stability`: `stable` routes are the
+integration surface, and breaking changes to them are named in the changelog;
+`internal` routes serve the bundled dashboard and can change in any release.
+
Nothing in this document duplicates a route table on purpose. Where a fact
below is derived from code, the file is named so the claim can be re-checked.
The default API address is `http://127.0.0.1:7337` (`docs/reference/CLI_REFERENCE.md`).
diff --git a/scripts/export_openapi.py b/scripts/export_openapi.py
new file mode 100644
index 000000000..7c13a1620
--- /dev/null
+++ b/scripts/export_openapi.py
@@ -0,0 +1,117 @@
+"""Export the server's OpenAPI document for a release, with a stability label per route.
+
+The release workflow attaches the output to each GitHub release as
+``openapi.json``, so anyone building on ``repowise serve`` can fetch one file
+that matches the version they run.
+
+Every operation gets ``x-repowise-stability``:
+
+- ``stable``: an integration surface. Breaking changes are named in the
+ changelog.
+- ``internal``: a payload shaped for the bundled dashboard. It can change in
+ any release without notice.
+
+The label comes from the operation's first tag. A tag missing from both sets
+fails the export, so a new router has to be classified before it ships.
+
+Run ``python scripts/export_openapi.py --out openapi.json``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+from typing import Any
+
+STABLE_TAGS = frozenset(
+ {
+ "blast-radius",
+ "c4",
+ "changes",
+ "chat",
+ "code-health",
+ "coupling",
+ "dead-code",
+ "decisions",
+ "doc-drift",
+ "events",
+ "external-systems",
+ "git",
+ "graph",
+ "health",
+ "jobs",
+ "pages",
+ "refactoring",
+ "repos",
+ "search",
+ "security",
+ "symbols",
+ "webhooks",
+ "workspace",
+ }
+)
+
+INTERNAL_TAGS = frozenset(
+ {
+ "actions",
+ "areas",
+ "claude-md",
+ "costs",
+ "episodes",
+ "feedback",
+ "files",
+ "history",
+ "knowledge-map",
+ "mcp",
+ "meta",
+ "modules",
+ "overview",
+ "owners",
+ "platform",
+ "providers",
+ "stats",
+ }
+)
+
+_HTTP_METHODS = frozenset({"get", "put", "post", "delete", "patch", "options", "head", "trace"})
+
+
+def label(spec: dict[str, Any]) -> dict[str, Any]:
+ """Stamp each operation with its stability, in place. Raise on an unclassified tag."""
+ unclassified: set[str] = set()
+ for item in spec.get("paths", {}).values():
+ for method, op in item.items():
+ if method not in _HTTP_METHODS:
+ continue
+ tags = op.get("tags") or []
+ tag = tags[0] if tags else "(untagged)"
+ if tag in STABLE_TAGS:
+ op["x-repowise-stability"] = "stable"
+ elif tag in INTERNAL_TAGS:
+ op["x-repowise-stability"] = "internal"
+ else:
+ unclassified.add(tag)
+ if unclassified:
+ raise ValueError(
+ "Classify these OpenAPI tags in scripts/export_openapi.py: " + ", ".join(sorted(unclassified))
+ )
+ return spec
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--out", type=pathlib.Path, default=pathlib.Path("openapi.json"))
+ args = parser.parse_args(argv)
+
+ from repowise.server.app import create_app
+
+ spec = label(create_app().openapi())
+ args.out.write_text(json.dumps(spec, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+ print(f"wrote {args.out} ({len(spec.get('paths', {}))} paths)", file=sys.stderr)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/unit/server/test_export_openapi.py b/tests/unit/server/test_export_openapi.py
new file mode 100644
index 000000000..31844568e
--- /dev/null
+++ b/tests/unit/server/test_export_openapi.py
@@ -0,0 +1,45 @@
+"""Every route in the released OpenAPI document carries a stability label."""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+
+import pytest
+
+_SCRIPT = pathlib.Path(__file__).resolve().parents[3] / "scripts/export_openapi.py"
+
+
+def _exporter():
+ spec = importlib.util.spec_from_file_location("_export_openapi", _SCRIPT)
+ assert spec and spec.loader
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_every_live_route_is_labelled() -> None:
+ from repowise.server.app import create_app
+
+ exporter = _exporter()
+ spec = exporter.label(create_app().openapi())
+
+ labels = {
+ op["x-repowise-stability"]
+ for item in spec["paths"].values()
+ for method, op in item.items()
+ if method in exporter._HTTP_METHODS
+ }
+ assert labels == {"stable", "internal"}
+
+
+def test_a_tag_in_both_sets_is_impossible() -> None:
+ exporter = _exporter()
+ assert not exporter.STABLE_TAGS & exporter.INTERNAL_TAGS
+
+
+def test_an_unclassified_tag_fails_the_export() -> None:
+ exporter = _exporter()
+ spec = {"paths": {"/x": {"get": {"tags": ["brand-new"]}}}}
+ with pytest.raises(ValueError, match="brand-new"):
+ exporter.label(spec)