View all connectors

GitHub Copilot Metrics

By enabling the GitHub Copilot connector, you can import user-level Copilot usage metrics. Please refer to the API documentation below and our schema explorer to see what data DX imports—note that DX does not read or access your source code.

The connector supports both enterprise-level and organization-level (non-enterprise) Copilot usage metrics. Only one level is used per customer—enterprise and org data are never mixed. Choose the setup that matches your GitHub structure.

Authentication methods

The GitHub Copilot connector supports three authentication methods:

  • Personal Access Token (PAT): Provides access to enterprise-level metrics, user-level metrics, and Copilot seat assignments. Enterprise only.
  • GitHub App (Enterprise): Provides access to user-level metrics via the enterprise users-1-day API. Enterprise only.
  • GitHub App (Organization): Provides access to user-level metrics via the org users-1-day API. For non-enterprise customers or org-level data.

All methods import data into the same github_copilot_daily_usages table. Enterprise data is identified by enterprise_slug; org-level data is identified by organization_id.

Note: The Copilot seat assignments API is optional, as active users can be determined from the users-1-day metrics. This is why GitHub App authentication, which only accesses the users-1-day endpoint, provides complete user-level usage data without requiring the seat assignments API.

GitHub App installation requirements

For detailed guidance on creating and installing GitHub Apps, see Registering a GitHub App and Installing your own GitHub App.

Enterprise-level GitHub App:

  • The GitHub App must be installed at the enterprise level (not organization level)
  • The app requires enterprise_copilot_metrics: read permission
  • Note that the enterprise-level metrics API and seat assignments API do not support GitHub App installation tokens, so only user-level daily metrics will be available

Organization-level GitHub App (non-enterprise):

  • The GitHub App is installed at the organization level (no enterprise installation required)
  • The app requires Organization: Copilot metrics (read) permission—see GitHub’s Copilot usage metrics documentation
  • DX iterates over your app installations and pulls metrics per organization using GET /orgs/{org}/copilot/metrics/reports/users-1-day
  • Org-level connection creation fails if enterprise-level data already exists for your account; similarly, org import is skipped if enterprise-level data exists

Prerequisites

For enterprise-level connections (PAT or Enterprise GitHub App):

For organization-level connections (non-enterprise GitHub App):

Setup instructions

Follow the steps below to connect GitHub to DX using your preferred authentication method.

Option 1: Personal Access Token (PAT)

This method provides access to all available Copilot metrics APIs.

Step 1

While signed into GitHub as an Enterprise Owner, navigate to Settings > Developer Settings > Personal Access Token.

Step 2

Click on Token (classic) > Generate new token (Classic). Either the manage_billing:copilot or read:enterprise scope is required.

Step 3

  • Navigate to the connections page in DX and select “+ Connection” in the top right.
  • Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.

Option 2: GitHub App (Enterprise)

This method provides access to user-level metrics only for enterprise customers.

Step 1

Create a GitHub App at the enterprise level with the following permission:

  • enterprise_copilot_metrics: read

Step 2

Install the GitHub App at the enterprise level. The installation must be at the enterprise level (not organization level) to access Copilot metrics.

Step 3

Navigate to the connections page in DX and select “+ Connection” in the top right. Select GitHub App authentication and enter your installation credentials.

Option 3: GitHub App non-enterprise

This method is for organizations that do not use GitHub Enterprise. It provides access to user-level metrics via the org-level API. Follow the full GitHub App registration and installation process.

Step 1

Browse to the URL below with ORGANIZATION_NAME replaced:

https://github.com/organizations/ORGANIZATION_NAME/settings/apps/new?public=false&url=https://getdx.com&request_oauth_on_install=false&setup_on_update=false&webhook_active=false

Step 2

This will pre-populate settings. Enter a name for your GitHub App (e.g. [COMPANYNAME] DX - GitHub Copilot). In the Permissions & events tab, set the following permission:

Scope Permission Description
Organization Copilot metrics Read-only (required)

See GitHub’s Copilot usage metrics documentation for details.

Step 3

Scroll to the bottom of the page and click Create GitHub App.

Step 4

The GitHub App ID will be shown at the top of the subsequent screen. Copy this ID for use in DX later.

Step 5

On the same screen, scroll down to Private keys and click Generate a private key to download a PEM file. Copy the contents of this file for use in DX later.

Step 6

Click Install App in the sidebar, then click Install beside each organization where you want Copilot metrics. No enterprise installation is required.

Step 7

Navigate to the connections page in DX and select “+ Connection” in the top right. Select GitHub App authentication and enter your App ID and private key.

Note: If you already have enterprise-level Copilot data in DX, org-level connection creation will fail. Use either enterprise-level or org-level connections, not both.

API reference

The table below lists the specific API endpoints that are used by DX. Please note that, to access these API endpoints, your Copilot Metrics API access policy must be enabled or set to “no policy” for your enterprise or organization.

Endpoint Reference
/enterprises/{enterprise}/copilot/billing/seats Link (PAT only, optional, enterprise)
/enterprises/{enterprise}/copilot/metrics/reports/users-1-day Link (PAT and GitHub App, enterprise)
/orgs/{org}/copilot/metrics/reports/users-1-day Link (GitHub App, org-level only)

Errors

The table below lists potential error codes when adding a connection in DX.

Error Description
invalid_credentials Your API credentials entered are not valid.
invalid_permissions Your API token or GitHub App does not have the permissions required by DX. For enterprise: verify your service account is an Enterprise Owner. For org-level: verify your GitHub App has Organization: Copilot metrics (read) and is installed to the organization.

Curl commands

When connection verification fails

When DX verifies a GitHub Copilot connection, it checks access to the relevant endpoints. If your connection is failing, you can test the endpoints directly using the curl commands below to troubleshoot the issue.

Enterprise (PAT): Replace YOUR_ENTERPRISE_SLUG with your enterprise slug and YOUR_TOKEN with your Personal Access Token.

Org-level (GitHub App): Replace YOUR_ORG with your organization login and YOUR_INSTALLATION_TOKEN with an installation access token from your GitHub App.

1. Test Copilot Seat Assignments Access (enterprise PAT only)

This verifies that your token can access Copilot seat assignments:

curl -H 'Accept: application/vnd.github+json' -H 'Authorization: Bearer YOUR_TOKEN' -H 'X-GitHub-Api-Version: 2022-11-28' 'https://api.github.com/enterprises/YOUR_ENTERPRISE_SLUG/copilot/billing/seats'

2. Test Copilot User 1-Day Usage Metrics (enterprise)

This verifies that your token can access daily user-level Copilot usage metrics. Replace YYYY-MM-DD with the date you want to inspect:

curl -H 'Accept: application/vnd.github+json' -H 'Authorization: Bearer YOUR_TOKEN' -H 'X-GitHub-Api-Version: 2022-11-28' 'https://api.github.com/enterprises/YOUR_ENTERPRISE_SLUG/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD'

3. Test Copilot User 1-Day Usage Metrics (org-level)

For org-level connections, test the organization API. Replace YOUR_ORG with your organization login and YOUR_INSTALLATION_TOKEN with an installation access token:

curl -H 'Accept: application/vnd.github+json' -H 'Authorization: Bearer YOUR_INSTALLATION_TOKEN' -H 'X-GitHub-Api-Version: 2022-11-28' 'https://api.github.com/orgs/YOUR_ORG/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD'

Troubleshooting

I’m seeing “no_resource” error from API response

This indicates that you don’t have admin access to the enterprise or organization account. Use the curl commands above to verify access to the required endpoints.

Copilot has been connected but all of my reports are blank

This indicates that a Copilot metrics API access policy has not yet been enabled for your enterprise or organization. For org-level connections, enable it per organization at https://github.com/organizations/ORGANIZATION_NAME/settings/copilot/policies.

Org-level connection fails with “enterprise data exists” or similar

You cannot use both enterprise-level and org-level Copilot connections for the same DX account. If enterprise-level data already exists, org-level connection creation will fail. Use one connection type only.