CodeBoarding · Svilen-Stefanov · Sep 24, 2026 · Sep 24, 2026
diff --git a/action.yml b/action.yml
@@ -359,6 +359,7 @@ runs:
       env:
         DEPTH_CAP: ${{ inputs.depth_cap }}
         CHECKOUT_DIR: ${{ github.workspace }}/.codeboarding-target
+        PR_NUMBER: ${{ steps.guard.outputs.pr_number }}
       run: python3 "$GITHUB_ACTION_PATH/scripts/action/run_meter.py" start
 
     - name: Setup Java for CodeBoarding

diff --git a/scripts/action/run_meter.py b/scripts/action/run_meter.py
@@ -71,12 +71,19 @@ def baseline_depth(checkout: Path) -> int | None:
 
 def start_request(environ: dict[str, str], depth: int, tier: str) -> dict:
     manifest = json.loads((ACTION_ROOT / ".release-please-manifest.json").read_text(encoding="utf-8"))
-    return {
+    body = {
         "depth": depth,
         "credential": "hosted" if tier in ("hosted", "license") else "own_key",
         "baseline_depth": baseline_depth(Path(environ.get("CHECKOUT_DIR", ""))),
         "client": {"surface": "action", "version": manifest["."]},
     }
+    # A /codeboarding comment's OIDC token names no pull request, so the proxy is told which.
+    pull_request = environ.get("PR_NUMBER", "")
+    if re.fullmatch(r"[1-9][0-9]*", pull_request) and not re.fullmatch(
+        r"refs/pull/[0-9]+/merge", environ.get("GITHUB_REF", "")
+    ):
+        body["pull_request"] = int(pull_request)
+    return body
 
 
 def start(environ: dict[str, str]) -> tuple[dict[str, str], int]:

diff --git a/tests/contracts/README.md b/tests/contracts/README.md
@@ -6,6 +6,8 @@ JSON Schemas (draft 2020-12) for the wire shapes licensing-aws answers and accep
 | --- | --- |
 | `session.schema.json` | answer of `POST /session/github` and `POST /session/extension` |
 | `me.schema.json` | answer of `GET /me` |
+| `usage.schema.json` | answer of `GET /me/usage`: this week's counted runs and opened private reviews, item by item |
+| `workspace-usage.schema.json` | answer of `GET /workspaces/{workspace}/usage` (admins of a Team or Enterprise organisation; 403 `reason: not_admin` or `no_plan` otherwise) |
 | `run-start.request.schema.json`, `run-start.response.schema.json` | `POST /run/start` on gha_proxy (OIDC) and license_proxy (extension token) |
 | `run-finish.request.schema.json`, `run-finish.response.schema.json` | `POST /run/finish` on both |
 | `meter-consume.request.schema.json`, `meter-consume.response.schema.json` | `POST /meter/consume` |

diff --git a/tests/contracts/examples/me.free-exhausted.json b/tests/contracts/examples/me.free-exhausted.json
@@ -44,6 +44,7 @@
       "login": "acme-corp",
       "plan": "free",
       "covered": false,
+      "admin": false,
       "members_permission": true,
       "bot_runs": {
         "meter": "bot_runs",

diff --git a/tests/contracts/examples/me.free-one-left.json b/tests/contracts/examples/me.free-one-left.json
@@ -44,6 +44,7 @@
       "login": "acme-corp",
       "plan": "free",
       "covered": false,
+      "admin": false,
       "members_permission": true,
       "bot_runs": {
         "meter": "bot_runs",

diff --git a/tests/contracts/examples/me.past-due.json b/tests/contracts/examples/me.past-due.json
@@ -44,6 +44,7 @@
       "login": "acme-corp",
       "plan": "free",
       "covered": false,
+      "admin": false,
       "members_permission": true,
       "bot_runs": {
         "meter": "bot_runs",

diff --git a/tests/contracts/examples/me.pro.json b/tests/contracts/examples/me.pro.json
@@ -44,6 +44,7 @@
       "login": "acme-corp",
       "plan": "free",
       "covered": false,
+      "admin": false,
       "members_permission": true,
       "bot_runs": {
         "meter": "bot_runs",

diff --git a/tests/contracts/examples/me.team.json b/tests/contracts/examples/me.team.json
@@ -47,6 +47,7 @@
       "login": "acme-corp",
       "plan": "team",
       "covered": true,
+      "admin": true,
       "members_permission": true,
       "bot_runs": {
         "meter": "bot_runs",

diff --git a/tests/contracts/examples/me.trial.json b/tests/contracts/examples/me.trial.json
@@ -44,6 +44,7 @@
       "login": "acme-corp",
       "plan": "free",
       "covered": false,
+      "admin": false,
       "members_permission": true,
       "bot_runs": {
         "meter": "bot_runs",

diff --git a/tests/contracts/examples/run-start.request.comment.json b/tests/contracts/examples/run-start.request.comment.json
@@ -0,0 +1,11 @@
+{
+  "depth": 5,
+  "credential": "hosted",
+  "baseline_depth": 2,
+  "pull_request": 482,
+  "client": {
+    "surface": "action",
+    "version": "1.17.0",
+    "editor": null
+  }
+}
diff --git a/tests/contracts/examples/usage.free-near-limit.json b/tests/contracts/examples/usage.free-near-limit.json
@@ -0,0 +1,75 @@
+{
+  "period": "2026-W39",
+  "resets_at": "2026-09-28T00:00:00+00:00",
+  "runs": {
+    "used": 4,
+    "limit": 5,
+    "by_you": 3,
+    "by_bots": 1,
+    "items": [
+      {
+        "key": "github:5550101#pr12",
+        "surface": "github",
+        "repository": "fresh-dev/todo-api",
+        "pr": 12,
+        "by": {
+          "kind": "person",
+          "login": "fresh-dev"
+        },
+        "first_run_at": "2026-09-23T10:15:00+00:00",
+        "updates": 0
+      },
+      {
+        "key": "vscode:1b3d5f7092a4c6e8f0a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e4",
+        "surface": "vscode",
+        "repository": "todo-api",
+        "pr": null,
+        "by": {
+          "kind": "person",
+          "login": "fresh-dev"
+        },
+        "first_run_at": "2026-09-22T19:40:00+00:00",
+        "updates": 1
+      },
+      {
+        "key": "github:5550101#pr11",
+        "surface": "github",
+        "repository": "fresh-dev/todo-api",
+        "pr": 11,
+        "by": {
+          "kind": "bot",
+          "login": "renovate[bot]"
+        },
+        "first_run_at": "2026-09-22T06:00:00+00:00",
+        "updates": 0
+      },
+      {
+        "key": "github:5550102#pr3",
+        "surface": "github",
+        "repository": null,
+        "pr": 3,
+        "by": null,
+        "first_run_at": null,
+        "updates": 0
+      }
+    ]
+  },
+  "reviews": {
+    "used": 2,
+    "limit": 3,
+    "items": [
+      {
+        "key": "github:5550101#pr12",
+        "repository": "fresh-dev/todo-api",
+        "pr": 12,
+        "opened_at": "2026-09-23T10:40:00+00:00"
+      },
+      {
+        "key": "github:5550101#pr10",
+        "repository": "fresh-dev/todo-api",
+        "pr": 10,
+        "opened_at": "2026-09-21T13:05:00+00:00"
+      }
+    ]
+  }
+}
diff --git a/tests/contracts/examples/usage.pro.json b/tests/contracts/examples/usage.pro.json
@@ -0,0 +1,120 @@
+{
+  "period": "2026-W39",
+  "resets_at": "2026-09-28T00:00:00+00:00",
+  "runs": {
+    "used": 7,
+    "limit": 40,
+    "by_you": 5,
+    "by_bots": 2,
+    "items": [
+      {
+        "key": "github:870011#pr2",
+        "surface": "github",
+        "repository": "Svilen-Stefanov/paywall-e2e",
+        "pr": 2,
+        "by": {
+          "kind": "person",
+          "login": "Svilen-Stefanov"
+        },
+        "first_run_at": "2026-09-22T16:40:00+00:00",
+        "updates": 0
+      },
+      {
+        "key": "github:870011#pr1",
+        "surface": "github",
+        "repository": "Svilen-Stefanov/paywall-e2e",
+        "pr": 1,
+        "by": {
+          "kind": "person",
+          "login": "Svilen-Stefanov"
+        },
+        "first_run_at": "2026-09-22T16:09:00+00:00",
+        "updates": 1
+      },
+      {
+        "key": "github:870011#pr4",
+        "surface": "github",
+        "repository": "Svilen-Stefanov/paywall-e2e",
+        "pr": 4,
+        "by": {
+          "kind": "bot",
+          "login": "dependabot[bot]"
+        },
+        "first_run_at": "2026-09-22T08:00:00+00:00",
+        "updates": 0
+      },
+      {
+        "key": "github:9919001#pr31",
+        "surface": "github",
+        "repository": "CodeBoarding/CodeBoarding",
+        "pr": 31,
+        "by": {
+          "kind": "person",
+          "login": "Svilen-Stefanov"
+        },
+        "first_run_at": "2026-09-21T15:20:00+00:00",
+        "updates": 2
+      },
+      {
+        "key": "github:9919002#run11809532110",
+        "surface": "github",
+        "repository": "CodeBoarding/CodeBoarding-action",
+        "pr": null,
+        "by": {
+          "kind": "person",
+          "login": "Svilen-Stefanov"
+        },
+        "first_run_at": "2026-09-21T11:30:00+00:00",
+        "updates": 0
+      },
+      {
+        "key": "vscode:9f2c4e1a7b3d5f60819a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e",
+        "surface": "vscode",
+        "repository": "CodeBoarding-webview",
+        "pr": null,
+        "by": {
+          "kind": "person",
+          "login": "Svilen-Stefanov"
+        },
+        "first_run_at": "2026-09-21T10:02:00+00:00",
+        "updates": 3
+      },
+      {
+        "key": "github:870011#pr3",
+        "surface": "github",
+        "repository": "Svilen-Stefanov/paywall-e2e",
+        "pr": 3,
+        "by": {
+          "kind": "bot",
+          "login": "dependabot[bot]"
+        },
+        "first_run_at": "2026-09-21T08:00:00+00:00",
+        "updates": 0
+      }
+    ]
+  },
+  "reviews": {
+    "used": 3,
+    "limit": 60,
+    "items": [
+      {
+        "key": "github:9919001#pr31",
+        "repository": "CodeBoarding/CodeBoarding",
+        "pr": 31,
+        "opened_at": "2026-09-23T09:12:00+00:00"
+      },
+      {
+        "key": "github:9919003#pr163",
+        "repository": "CodeBoarding/CodeBoarding-webview",
+        "pr": 163,
+        "opened_at": "2026-09-22T14:30:00+00:00"
+      },
+      {
+        "key": "github:9919001#pr28",
+        "repository": "CodeBoarding/CodeBoarding",
+        "pr": 28,
+        "opened_at": "2026-09-21T17:45:00+00:00"
+      }
+    ]
+  }
+}
diff --git a/tests/contracts/examples/usage.team.json b/tests/contracts/examples/usage.team.json
@@ -0,0 +1,60 @@
+{
+  "period": "2026-W39",
+  "resets_at": "2026-09-28T00:00:00+00:00",
+  "runs": {
+    "used": 12,
+    "limit": 60,
+    "by_you": 12,
+    "by_bots": 0,
+    "items": [
+      {
+        "key": "github:9919001#pr35",
+        "surface": "github",
+        "repository": "CodeBoarding/CodeBoarding",
+        "pr": 35,
+        "by": {
+          "kind": "person",
+          "login": "ivanmilevtues"
+        },
+        "first_run_at": "2026-09-23T11:02:00+00:00",
+        "updates": 0
+      },
+      {
+        "key": "github:9919001#pr34",
+        "surface": "github",
+        "repository": "CodeBoarding/CodeBoarding",
+        "pr": 34,
+        "by": {
+          "kind": "person",
+          "login": "ivanmilevtues"
+        },
+        "first_run_at": "2026-09-23T08:47:00+00:00",
+        "updates": 4
+      },
+      {
+        "key": "vscode:4d6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a6b",
+        "surface": "vscode",
+        "repository": "CodeBoarding",
+        "pr": null,
+        "by": {
+          "kind": "person",
+          "login": "ivanmilevtues"
+        },
+        "first_run_at": "2026-09-22T09:30:00+00:00",
+        "updates": 6
+      }
+    ]
+  },
+  "reviews": {
+    "used": 9,
+    "limit": 100,
+    "items": [
+      {
+        "key": "github:9919001#pr35",
+        "repository": "CodeBoarding/CodeBoarding",
+        "pr": 35,
+        "opened_at": "2026-09-23T11:20:00+00:00"
+      }
+    ]
+  }
+}