chore(sentry-instrument): regenerate semantics weekly

Run the semantics generator every Monday and commit changed references to
main. Keep the instrument skill's domain links synchronized as categories
change.

Co-Authored-By: Evan Purkhiser <evan.purkhiser@sentry.io>

Author: sentry-junior[bot]

.github/workflows/regen-semantics.yml

@@ -0,0 +1,70 @@
+# Refresh the generated Sentry semantic-convention references once a week.
+# The release App token is required because this workflow commits directly to
+# main and GITHUB_TOKEN pushes do not trigger the normal push workflows.
+
+name: Regenerate semantic conventions
+
+on:
+  schedule:
+    - cron: "17 13 * * 1"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: regenerate-semantic-conventions
+  cancel-in-progress: false
+
+jobs:
+  regenerate:
+    if: github.repository == 'getsentry/sentry-for-ai'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - name: Get auth token
+        id: token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }}
+          private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }}
+
+      - name: Checkout main
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: main
+          token: ${{ steps.token.outputs.token }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Regenerate references
+        run: |
+          set -euo pipefail
+          python3 scripts/gen-semantics.py
+
+          # flowmark exits non-zero when it rewrites files. Run it once to
+          # apply fixes, then again to prove the generated tree is stable.
+          ./scripts/lint.sh run flowmark --files \
+            src/references/semantics/*.md \
+            src/skills/sentry-instrument/SKILL.md || true
+          ./scripts/lint.sh run flowmark --files \
+            src/references/semantics/*.md \
+            src/skills/sentry-instrument/SKILL.md
+          ./scripts/lint.sh run built-links
+
+      - name: Commit changes
+        run: |
+          set -euo pipefail
+
+          if git diff --quiet -- src/references/semantics src/skills/sentry-instrument/SKILL.md; then
+            echo "No semantic-convention changes."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add src/references/semantics src/skills/sentry-instrument/SKILL.md
+          git commit -m "chore(sentry-instrument): regenerate semantic conventions"
+          git push origin HEAD:main

scripts/gen-semantics.py

@@ -16,6 +16,9 @@
 SOURCE_URL = "https://getsentry.github.io/sentry-conventions/api/attributes.json"
 REPO_ROOT = Path(__file__).resolve().parents[1]
 OUT_DIR = REPO_ROOT / "src" / "references" / "semantics"
+SKILL_PATH = REPO_ROOT / "src" / "skills" / "sentry-instrument" / "SKILL.md"
+TOC_START = "<!-- semantics-toc:start -->"
+TOC_END = "<!-- semantics-toc:end -->"
 
 # One-line domain intros shown at the top of each file. Keep these about the
 # domain, not about how the file was generated.
@@ -157,7 +160,24 @@ def main() -> None:
         lines.append("")
         (OUT_DIR / f"{cat}.md").write_text("\n".join(lines), encoding="utf-8")
 
-    print(f"wrote {len(by_cat)} domain files ({len(stable)} stable attrs) -> {OUT_DIR.relative_to(REPO_ROOT)}")
+    skill = SKILL_PATH.read_text(encoding="utf-8")
+    before, marker, tail = skill.partition(TOC_START)
+    if not marker:
+        raise RuntimeError(f"missing {TOC_START} in {SKILL_PATH}")
+    _, marker, after = tail.partition(TOC_END)
+    if not marker:
+        raise RuntimeError(f"missing {TOC_END} in {SKILL_PATH}")
+    links = "\n".join(
+        f"- [`{cat}`](references/semantics/{cat}.md)" for cat in sorted(by_cat)
+    )
+    SKILL_PATH.write_text(
+        f"{before}{TOC_START}\n{links}\n{TOC_END}{after}", encoding="utf-8"
+    )
+
+    print(
+        f"wrote {len(by_cat)} domain files ({len(stable)} stable attrs) and refreshed "
+        f"{SKILL_PATH.relative_to(REPO_ROOT)}"
+    )
 
 
 if __name__ == "__main__":

src/skills/sentry-instrument/SKILL.md

@@ -101,6 +101,7 @@ When naming custom span or log attributes, open **only** the matching domain ref
 below. Prefer these stable keys over invented names.
 Deprecated attributes are omitted.
 
+<!-- semantics-toc:start -->
 - [`angular`](references/semantics/angular.md)
 - [`app`](references/semantics/app.md)
 - [`art`](references/semantics/art.md)
@@ -159,6 +160,7 @@ Deprecated attributes are omitted.
 - [`user`](references/semantics/user.md)
 - [`user_agent`](references/semantics/user_agent.md)
 - [`vercel`](references/semantics/vercel.md)
+<!-- semantics-toc:end -->
 
 ## Step 4 — Verify it landed