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: https://github.com/settings/tokens

• "Copilot usage metrics" policy enabled in your GitHub organization settings (Settings > Copilot > Policies)

• Revenium API key (hak_ or rev_ prefix). Get it from Settings > API Keys in the Revenium dashboard.

• Node.js >= 20.19.0

1. Install the Revenium CLI

npm install -g @revenium/cli

You can also use npx without installing globally:

npx @revenium/cli revenium-copilot setup

2. Run the setup wizard

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

revenium-copilot status

Confirms that both the GitHub API and Revenium endpoint are reachable with the provided credentials. If either shows "unreachable", see Troubleshooting below.

4. Send a test metric

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.

# 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

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.

6. Backfill historical data

To import historical Copilot data beyond the default 28-day window:

# 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

GitHub retains Copilot metrics for a limited window (typically 28 days). Older data may not be available depending on your GitHub plan.

7. Reset configuration

To remove the stored configuration and start fresh:

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 https://github.com/settings/tokens.

• 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 Settings > API Keys 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:

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 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 <date> --to <date>	Sync a specific date range (YYYY-MM-DD)
revenium-copilot sync --dry-run	Preview sync output without sending
revenium-copilot backfill --since <date> --to <date>	Import historical data
revenium-copilot reset	Remove configuration and start fresh