Connect a source

Connect GitHub

Paste a fine-grained personal access token and your organization's name, and Costfluent imports the organization's metered GitHub usage cost by day, product and repository.

Costfluent reads your GitHub spend from the organization's metered usage report, with a fine-grained personal access token you create for it. One connection is one GitHub organization, and everything GitHub bills it by usage: Actions, Packages, Git LFS, Codespaces, Copilot and shared storage.

How Costfluent connects

You give Costfluent the token and the organization's name. Costfluent stores them encrypted and uses the token for one kind of request: the organization's usage report for one UTC day, from GitHub's billing API. The organization identifies the connection, and the token is only ever used for that connection. An enterprise account connects each of its organizations on its own.

Read-only “Administration” access, which the billing report needs, also lets the token read the organization's settings, though it can change nothing. Create the token for Costfluent alone, so you can revoke it without touching anything else.

Prerequisites

  1. The Owner or Integration owner organization role in Costfluent.
  2. An owner of the GitHub organization, who creates the token: a token reads the billing only while its owner is an owner of the organization.
  3. The organization on GitHub's enhanced billing platform. GitHub serves the usage report only for organizations on it.

Connect

Create the token on GitHub

  1. Signed in as an owner of the organization, open your account's “Settings”, then “Developer settings”, “Personal access tokens”, “Fine-grained tokens”, and select “Generate new token”.
  2. Name it for Costfluent, set “Resource owner” to the organization and choose an expiration.
  3. Under “Repository access”, choose “Public repositories”. The billing report needs no repository permission.
  4. Under the organization permissions, set “Administration” to “Read-only”, and add no other permission.
  5. Generate the token and copy it. GitHub shows it only once.
  6. If the organization requires approval of fine-grained tokens, approve the request in the organization's “Settings”, under “Personal access tokens”, “Pending requests”.

Connect in Costfluent

  1. Open Settings, then Integrations, select GitHub, and open the Connect tab.
  2. Select "Add access token", keep the suggested Display name or enter your own, paste the token into Personal access token, and enter the organization's name as in its address, github.com/<name>, into Organization.
  3. Select "Test connection" to see each check, or "Connect" to save.

Costfluent reads the organization's usage with the token before storing anything, so a connection that saves can read your cost. A token that may not read the organization's billing is refused, and so is a connection with the same organization as an existing one. GitHub does not distinguish upper and lower case in an organization's name, so neither does Costfluent.

Data and freshness

Connecting imports as far back as your plan's backfill reaches, and at most six months (Manage connections), as long as GitHub reports usage that far back. Cost arrives by UTC day, in US dollars, the currency GitHub bills in.

Later syncs read the most recent days again, so a day whose usage GitHub changes afterwards is updated. Billed cost is GitHub's net amount: the gross amount less the usage your GitHub plan includes, which GitHub states as a discount. The gross amount is the list cost, so usage within what your plan includes has a list cost and a billed cost of zero.

GitHub's API reports usage by product, SKU and repository only. Cost per user or per workflow is not available: GitHub puts it only in the detailed usage report it sends by email.

Reporting dimensions

  • Sub-account is the organization.
  • Service is the GitHub product the usage is billed under, such as Actions, Codespaces or Copilot.
  • Service category is AI and Machine Learning for Copilot, with Service subcategory Generative AI, and Developer Tools for every other product.
  • SKU is GitHub's SKU for what was used.
  • Resource is the repository the usage belongs to. A charge for the organization as a whole, such as a Copilot seat, has none.
  • The billing account is the organization, and the billing period is the UTC calendar month.

Update or disconnect

After connecting

The Manage tab lists the connection by its display name, with its GitHub organization. Open the gear icon beside it to see whether the usage is still readable, which workspaces the connection feeds, and which months have been imported. Run checks runs the checks again on request.

Rotating or removing access

GitHub does not rotate the token for you. When it expires, or its owner leaves the organization, collection stops until you paste a new one. Before that, create a new token the same way, select Update credentials on the connection page and paste it with the same organization's name; then delete the old token under “Fine-grained tokens”. Another organization is refused.

To retire the connection, remove it in Costfluent and delete its token on GitHub. Removing it erases the cost it imported (Remove a connection).

Troubleshooting

  • GitHub refused this token. The token is wrong, has expired or was revoked, or its resource owner is not the organization. Create a fine-grained personal access token whose resource owner is the organization, and paste it.
  • This token may not read the billing of organization … The token lacks the organization permission “Administration” with read access, its owner is not an owner of the organization, or the organization requires approval of fine-grained tokens and has not approved it yet. Give it the permission, check its owner's role, and approve the pending request.
  • GitHub found no billing usage for organization … The organization's name is wrong, the token's resource owner is another organization, or the organization is not yet on GitHub's enhanced billing platform, which the usage report needs.
  • A GitHub organization's name is the one in its address, github.com/<name>: letters, digits and single hyphens, at most 39 characters. What was entered is not the organization's name, for example its display name or the whole address. Enter the name that follows github.com/.
  • This key belongs to another organization. Shown when updating credentials: the organization entered is not the one this connection collects. Connect that organization as a new connection.