# Connect GitHub

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.

:::caution
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

<Stepper>

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”.

</Stepper>

### Connect in Costfluent

<Stepper>

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.

</Stepper>

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](/connect/manage-connections#how-it-behaves)), as long as GitHub reports usage
that far back. Cost arrives by UTC day, in US dollars, the currency GitHub bills in.

:::note
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.
:::

:::note
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](/connect/manage-connections#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.
