> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/setup-copilot.md). # Setup GitHub Copilot The Revenium CLI syncs GitHub Copilot Business and Enterprise usage metrics from the GitHub Copilot Metrics API into Revenium via OTLP. It tracks code completions, chat interactions, lines of code suggested and accepted, and active users per IDE and language. **Requirements:** * GitHub Copilot Business or Enterprise active on your organization * GitHub PAT (classic) with the following scopes: * `manage_billing:copilot` * `read:org` * Generate at: * "Copilot usage metrics" policy enabled in your GitHub organization settings (Settings > Copilot > Policies) * Revenium API key (`hak_` or `rev_` prefix). Get it from Connections > SDK Setup in the Revenium dashboard. * Node.js >= 20.19.0 ## 1. Install the Revenium CLI ```bash npm install -g @revenium/cli ``` You can also use `npx` without installing globally: ```bash npx @revenium/cli revenium-copilot setup ``` ## 2. Run the setup wizard ```bash revenium-copilot setup ``` The wizard prompts for: * **GitHub personal access token** — validated against the `ghp_` or `github_pat_` prefix * **GitHub organization slug** — the org whose Copilot usage you want to track * **Revenium API key** — validated against the `hak_` or `rev_` prefix * **Copilot subscription tier** — individual, business, or enterprise * **Email** (optional) — for attribution * **Organization name** (optional) — for grouping usage * **Product name** (optional) — for sub-segmenting within the organization * **Sync interval** (optional) — defaults to 5 minutes The wizard tests connectivity to both the GitHub Copilot Metrics API and the Revenium endpoint before writing the configuration. Configuration is saved to `~/.github-copilot/revenium/revenium.env` with restricted file permissions (owner read/write only). ## 3. Verify the configuration ```bash revenium-copilot status ``` Confirms that both the GitHub API and Revenium endpoint are reachable with the provided credentials. If either shows "unreachable", see [Troubleshooting](#troubleshooting) below. ## 4. Send a test metric ```bash revenium-copilot test --verbose ``` Sends a zero-cost synthetic event to verify the Revenium pipeline is processing Copilot data. Check AI Assistants > Copilot > Integration Logs to confirm receipt. ## 5. Sync usage data Pulls Copilot usage from the GitHub API and sends it to Revenium. GitHub usage data has an approximately 24-hour delay. ```bash # One-time sync (last 28 days): revenium-copilot sync # Continuous sync (recommended for production): revenium-copilot sync --watch # Custom date range: revenium-copilot sync --from 2025-01-01 --to 2025-01-31 # Preview what would be sent without actually sending: revenium-copilot sync --dry-run ``` {% hint style="info" %} **Continuous sync** runs on the interval configured during setup (default: 5 minutes). It deduplicates data automatically, so restarting the process does not create duplicate records. {% endhint %} ## 6. Backfill historical data To import historical Copilot data beyond the default 28-day window: ```bash # Backfill a specific date range: revenium-copilot backfill --since 2025-01-01 --to 2025-06-01 # Preview without sending: revenium-copilot backfill --since 2025-01-01 --to 2025-06-01 --dry-run # Verbose output: revenium-copilot backfill --since 2025-01-01 --to 2025-06-01 -v ``` {% hint style="warning" %} GitHub retains Copilot metrics for a limited window (typically 28 days). Older data may not be available depending on your GitHub plan. {% endhint %} ## 7. Reset configuration To remove the stored configuration and start fresh: ```bash revenium-copilot reset ``` This deletes the configuration at `~/.github-copilot/revenium/` and removes the shell profile source line. You can then run `revenium-copilot setup` again with new credentials. ## Troubleshooting Start every diagnosis with `revenium-copilot status`. It checks that the configuration exists at `~/.github-copilot/revenium/revenium.env`, parses correctly, and can reach **both** the GitHub Copilot Metrics API and the Revenium endpoint — and it prints the sync state so you can see whether any data has been pulled yet. ### No data appears in Revenium after setup Copilot metering is **pull-based**: the CLI reads usage from the GitHub Copilot Metrics API and forwards it to Revenium on a schedule. Two things commonly delay the first data: 1. **GitHub's reporting delay.** GitHub aggregates Copilot metrics with an approximately **24-hour delay**, so today's activity will not be available to pull yet. An empty recent window is expected. 2. **The sync must be running.** Run `revenium-copilot status` and check **Sync State** — "No sync has been performed yet" means nothing has been pulled. Run `revenium-copilot sync` for a one-time pull (last 28 days), or `revenium-copilot sync --watch` to keep pulling on the configured interval (default 5 minutes). For ongoing metering, `--watch` must stay running. 3. **Confirm the pipeline.** Run `revenium-copilot test --verbose`, then open **AI Assistants > Copilot > Integration Logs** to confirm the event was received. If the test event lands but real usage does not, the sync is not running or GitHub's 24-hour window has not yet caught up. ### `status` reports "GitHub Copilot API unreachable" The GitHub side of the pipeline is failing. Check, in order: * **PAT scopes.** The GitHub personal access token (classic) must carry both `manage_billing:copilot` and `read:org`. A token missing either scope cannot read the metrics API. Regenerate it at . * **Metrics policy.** The "Copilot usage metrics" policy must be enabled for your organization under **Settings > Copilot > Policies**. With the policy off, GitHub returns no metrics even to a correctly-scoped token. * **Organization slug + plan.** Confirm the org slug entered during setup is correct and that the org has Copilot **Business or Enterprise** active — usage metrics are not available on individual plans. ### `status` reports "Revenium API unhealthy", or authentication is rejected The Revenium side of the pipeline is failing: * **Verify the key type.** Copilot telemetry authenticates with a **Revenium** API key (`hak_` or `rev_` prefix), not a GitHub token. A `hak_` key must be in `hak_{tenant}_{key}` form. Get one from **Connections > SDK Setup** in the Revenium dashboard. * **Verify the endpoint.** The default is `https://api.revenium.ai`. * **Re-enter credentials.** Run `revenium-copilot setup` to rewrite the configuration with a corrected key or endpoint. If `status` reports a Revenium connection failure rather than an auth rejection, confirm your data can actually reach Revenium with a one-line self-test from any terminal — substitute your Revenium key: ```bash curl -sS -o /dev/null -w "%{http_code}\n" \ -X POST "https://api.revenium.ai/meter/v2/otlp/v1/logs" \ -H "x-api-key: rev_mk_your_tenant_yourkey" \ -H "Content-Type: application/json" \ -d '{"resourceLogs":[]}' ``` * **`200` / `202`** — your endpoint and key are reaching Revenium correctly. * **`401` / `403` with an auth message** — the key is wrong, inactive, or not a Revenium key. * **`403` with no auth body, or a connection failure** — the request is being stopped before it reaches Revenium (for example a corporate network or proxy). [Contact Revenium support](https://www.revenium.io/contact) with your egress IP range so we can confirm connectivity. ### Older historical data is missing on backfill GitHub retains Copilot metrics for a limited window (typically **28 days**). Data older than that window may not be available to backfill, depending on your GitHub plan. ## Command reference | Command | Description | | ------------------------------------------------------ | ------------------------------------------ | | `revenium-copilot setup` | Interactive setup wizard | | `revenium-copilot status` | Verify connectivity to GitHub and Revenium | | `revenium-copilot test --verbose` | Send a synthetic test event | | `revenium-copilot sync` | One-time sync (last 28 days) | | `revenium-copilot sync --watch` | Continuous sync at configured interval | | `revenium-copilot sync --from --to ` | Sync a specific date range (YYYY-MM-DD) | | `revenium-copilot sync --dry-run` | Preview sync output without sending | | `revenium-copilot backfill --since --to ` | Import historical data | | `revenium-copilot reset` | Remove configuration and start fresh | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/setup-copilot.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.