Skip to main content

​
Overview

Connect GitHub to nOps with a personal access token and your organization slug (and optionally an enterprise slug if you report at enterprise level). We validate the token before saving it, store it securely, and never show it again in the UI. We recommend a fine-grained PAT owned by your organization: you can grant read-only org and repository permissions instead of the broad classic scopes. If you need enterprise billing or consumed licenses, use a classic PAT for that part. GitHub does not support those endpoints on fine-grained tokens. This card is your cost and usage integration. It is separate from GitHub Issues in Clara’s recommendation workflow (that flow uses WorkOS Pipes and a repository destination). Connecting here does not turn on issue creation. After you connect, nOps can ingest:
  • Cost and usage: metered spend by product, SKU, repository, and day (Actions, Codespaces, Packages, storage, Copilot, GHAS, and more).
  • Copilot attribution: premium requests and AI credits by user and model, plus Copilot seat assignments when your token allows it.
  • Members and seats: your organization member roster and paid seat counts.
  • Engineering activity: read-only metadata from pull requests, commits, and Actions runs to enrich anomaly context (no source code or file contents).
Only nOps admins and owners can connect, re-validate, or disconnect. Members see Admin Only on the integration card.

​
Who can create the token?

The person who creates the token needs the right role in GitHub: Your org or enterprise should use GitHub’s enhanced billing platform (required for the billing usage APIs nOps calls). You also need nOps Settings → Integrations admin access to connect the card.

​
Choose your token type

The connect modal asks you to pick Fine-grained PAT (recommended) or Classic PAT. The permission checklist in the modal matches the lists below. Create the token with Resource owner = your organization (not your personal account). Grant read-only permissions. nOps only sends GET requests. Organization permissions
  • Administration: read: organization billing usage, premium requests, AI credits
  • Members: read: member roster
  • GitHub Copilot Business: read: Copilot seats (optional, if you use Copilot)
  • Organization Copilot metrics: read: Copilot usage metrics (optional)
Repository permissions: set access to All repositories (or every repo your engineers use; repos the token cannot see are omitted from activity data)
  • Metadata: read: repository list (included automatically)
  • Pull requests: read: PR metadata for activity context
  • Contents: read: commit metadata on the default branch (not file contents)
  • Actions: read: workflow run metadata
Do not add an Enterprise slug in nOps when you use a fine-grained token. Enterprise billing usage and consumed licenses require a classic PAT with read:enterprise. Use fine-grained for org-level billing and activity, or switch to classic if you need enterprise reporting.
Fine-grained tokens are a good fit for a dedicated service account with a short expiry and regular rotation. They avoid classic repo, which includes write access to private repositories.

​
Classic PAT

Use a classic token when you need enterprise billing, when fine-grained org billing is unavailable for your org, or when you prefer the older scope model. Scopes to select
  • admin:org: required for organization billing (read:org and write:org are not enough; GitHub often returns “not found” instead of “forbidden” when billing scope is missing)
  • manage_billing:copilot: Copilot seats (optional)
  • read:enterprise: required if you enter an Enterprise slug (enterprise billing and consumed licenses)
  • repo: private repository activity (optional for activity data; includes write. Prefer fine-grained for read-only repo access)
What nOps does with admin:org. GitHub treats organization billing as org administration. There is no separate “billing-only” classic scope for orgs. nOps uses these credentials only to read billing, Copilot, and member endpoints, never to change org settings, teams, or membership. Use a service account, limit scopes to what you need, and rotate on a schedule.

​
Create the token in GitHub

​
Fine-grained

  1. Sign in to GitHub as an org owner or billing manager.
  2. Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens.
  3. Click Generate new token, set Resource owner to your organization, and choose All repositories (or the repos you need).
  4. Add the organization and repository permissions from the list above.
  5. Set an expiration, generate the token, and copy it. GitHub shows it once.

​
Classic

  1. Sign in as an org owner, billing manager, or enterprise admin (as needed).
  2. Go to Settings → Developer settings → Personal access tokens → Tokens (classic).
  3. Click Generate new token (classic), add a note (for example nOps Inform), and set an expiration.
  4. Select the scopes from the classic list above.
  5. Generate and copy the token immediately.
For API details, see GitHub’s billing usage REST API and Automating usage reporting.

​
Connect in nOps

​
Where to open GitHub

  • First-time connect: Settings → Integrations, then the GitHub card.
  • Manage an existing connection: Settings → Account Status → Connected apps, then the GitHub chip.

​
Connect steps

  1. Open the GitHub modal.
  2. Choose Token type (fine-grained or classic).
  3. Paste your token (github_pat_… or ghp_…). nOps detects the prefix if it does not match your selection and shows a clear error.
  4. Enter your Organization slug (the URL segment from github.com/your-org, not the display name).
  5. Optionally enter an Enterprise slug (classic PAT only).
  6. Click Connect.
nOps calls the GitHub API to confirm the token and billing access before storing credentials. If something is wrong, you’ll see a specific message in the modal (missing scope, wrong slug, enterprise + fine-grained mismatch, and so on).

​
Manage your connection

From the same modal, admins can Re-validate (check the stored token still works), Update (new token or slugs), or Disconnect. Rotate tokens in GitHub before they expire, then update the connection in nOps.

​
Troubleshooting

  • Invalid token: Confirm the token owner has a billing or admin role and the token has not expired.
  • Fine-grained + enterprise slug: Remove the enterprise slug or switch to a classic PAT with read:enterprise.
  • Token type mismatch: If you chose Classic but pasted github_pat_…, switch the dropdown to Fine-grained (or paste a ghp_… classic token).
  • Organization not found / validation fails: Double-check the slug from the URL. For classic org billing, add admin:org. For fine-grained, grant Administration: read on a token whose resource owner is the org. The token owner must still be an org owner or billing manager.
  • No enterprise data: Use a classic PAT with read:enterprise and an enterprise billing role.
  • No Copilot or member data: Add Copilot or Members permissions (fine-grained) or manage_billing:copilot / member-related classic access. Missing optional permissions skip those datasets but do not block core cost and usage.
  • No billing data: Your org may not be on the enhanced billing platform yet; check GitHub billing settings.
  • No data in Inform yet: Allow up to 24 hours after the first successful connect for the initial sync.

​
Security

Treat the token like a password: do not commit it to git or share it in chat. Grant the minimum read permissions you need, use a service account where possible, rotate on a schedule, and disconnect in nOps when you retire a token.

​
Reference