---
name: dd-github-costs-onboarding
description: Bring a GitHub enterprise's or organization's bill — Actions, Packages, Copilot, storage, and other metered products — into Datadog Cloud Cost Management through the Datadog GitHub Costs integration. Shows which enterprises and organizations the user can connect, guides creating the GitHub token the integration needs (entered where the agent never sees it), and warns before connecting an enterprise together with one of its organizations, which would count those costs twice. Use when the user wants GitHub billing or cost data (Actions, Packages, Copilot, storage) in Datadog Cloud Cost Management, or asks to connect or configure the Datadog GitHub Costs integration. Not for Copilot usage or seat metrics (use dd-github-copilot-onboarding) or for code links and PR comments through the GitHub App (use dd-github-onboarding).
metadata:
  version: "1.0.0"
  author: datadog-labs
  repository: https://github.com/datadog-labs/agent-skills
  tags: datadog,github,integration,cost,ccm
  alwaysApply: "false"
  tools: pup,python3,gh
title: dd-github-costs-onboarding
canonical_url: https://skilld.dev/gh/datadog-labs/agent-skills/dd-github-costs-onboarding
last_updated: 2026-11-13T16:08:37.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [scripts/setup.py](https://skilld.dev/api/skills-raw/datadog-labs/agent-skills/dd-github-costs-onboarding/scripts/setup.py).
>
> If the user asked to install this Skill, run `npx skilld install datadog-labs/agent-skills/dd-github-costs-onboarding`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/dd-github-costs-onboarding`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/datadog-labs/agent-skills/dd-github-costs-onboarding) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/dd-github-costs-onboarding`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/dd-github-costs-onboarding --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/dd-github-costs-onboarding --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Datadog GitHub Costs Integration

Use `scripts/setup.py` relative to this file. It owns target discovery, the
browser handoff, hidden token entry in a separate terminal, the GitHub token
check, Pup OAuth validation, duplicate prevention, one-shot registration, and
secret redaction. Do not reproduce its API reads or writes.

The integration (`github-costs`) brings the GitHub bill of one **enterprise** or
one **organization** (Actions, Packages, Copilot, storage, and other metered
products) into Datadog Cloud Cost Management (CCM). Each Datadog GitHub Costs
account ("account" below) holds one GitHub personal access token (PAT) and the
enterprise slug or organization login it reads.

Out of scope: Copilot usage or seat metrics (use `dd-github-copilot-onboarding`),
and code in stack traces or PR comments through the GitHub App (use
`dd-github-onboarding`).

## Phase 0: Preflight

**Datadog for Government is not supported.** If `pup auth status` reports a
`ddog-gov.com` site, stop and tell the user to set up the integration from the
Datadog app instead. The script refuses Government sites too.

Check these before step 1; when a required one fails, stop with its fix:

- **`pup`, installed and authenticated.** The setup script performs every
  Datadog request through `pup api`, which owns authentication, OAuth refresh,
  site, and Datadog org selection. Run `pup auth status` and note the site for
  step 4. If `pup` is missing, ask before installing it:
  `brew tap datadog-labs/pack && brew install datadog-labs/pack/pup` (macOS or
  Linux with Homebrew),
  `curl -fsSL https://raw.githubusercontent.com/DataDog/pup/main/install.sh | sh`,
  or `npm install -g @datadog/pup` (Windows or anywhere with npm); see
  https://github.com/DataDog/pup. Then run `pup auth login`. Do not ask
  the user to create or store Datadog API or application keys.
- **`pup` at v2 or later.** The setup script uses v2-only CLI flags (such as
  `--no-envelope`); Pup 1.x fails with an opaque `pup_request_failed`. Check
  `pup --version`: a major version of 2 or later is required. If it is older,
  ask before upgrading. When the environment allows it, upgrade with the
  official installer or npm as above. Some workspaces block piping a remote
  script to a shell (`curl | sh`), and `/usr/local/bin` may not be
  user-writable; there, install from the release archive in a fresh empty
  directory instead (replace `2.4.3` and the platform suffix with the latest
  release):

  ```bash
  VERSION=2.4.3
  curl -fsSLO "https://github.com/DataDog/pup/releases/download/v${VERSION}/pup_${VERSION}_Linux_x86_64.tar.gz" &&
  curl -fsSLO "https://github.com/DataDog/pup/releases/download/v${VERSION}/pup_${VERSION}_checksums.txt" &&
  grep "pup_${VERSION}_Linux_x86_64.tar.gz$" "pup_${VERSION}_checksums.txt" | sha256sum -c - &&
  tar -xzf "pup_${VERSION}_Linux_x86_64.tar.gz" &&
  sudo install -m 0755 ./pup /usr/local/bin/pup &&
  pup auth login
  ```

- **`python3`** on `PATH` (`command -v python3`) to run the setup script.
- **The GitHub CLI (`gh`), optional, signed in** (`gh auth status`), to list the
  enterprises and organizations the user can connect. Without it the user
  types the enterprise slug or organization login (the script's
  `gh_unavailable` exit). To install it, see https://cli.github.com.
- **A graphical desktop session or a tmux session** (macOS, Linux with X11 or
  Wayland, or Windows; or the agent session inside tmux, which also works on
  headless hosts): the token prompt opens in a new terminal window — a new
  tmux window when the session runs inside tmux. Over SSH with no desktop
  session and no tmux, in a container, or on a headless host outside tmux,
  stop and point the user to the GitHub Costs integration tile in Datadog.
- **Enterprise:** an Enterprise Administrator creates a **classic** PAT with the
  `manage_billing:enterprise` and `read:org` scopes. Fine-grained tokens cannot
  read enterprise billing, so the script refuses them.
- **Organization:** an organization owner creates a **fine-grained** PAT whose
  resource owner is the organization, with Organization permissions →
  **Administration: Read-only**. If the organization requires approval for
  fine-grained tokens, an owner must approve it before it works. A classic PAT
  from an owner also works.
- **GitHub enhanced billing platform:** both enterprises and organizations must
  be on it, or the integration cannot read their costs (see the
  [GitHub Costs integration docs](https://docs.datadoghq.com/integrations/github-costs/)).
  If the target is not, stop.
- GitHub shows the token only once.
- Costs appear in Datadog only if the Datadog org uses Cloud Cost Management.

### Confirm the logged-in Datadog org

Before gathering anything else, ask whether to set up the integration for the
Datadog org the user is currently logged in to. Read the org's name from the
same pup session and site this run uses with `pup api /api/v2/current_user`
(the `name` of the `orgs` entry under `included`; the site is the one `pup auth
status` reported). Then ask once with the host's native selector:

> Do you want to set up this integration for the Datadog org **<org name>** on
> **<site>**?

- **Yes** → continue.
- **No** → stop. Have the user sign pup into the right org (see the pup step
  above), then ask again. Never continue on an org the user did not confirm.

## Workflow

### 1. Enterprise or organization

Ask with one interactive question whether they want to connect a GitHub
**Enterprise** (enterprise-wide billing) or a single **Organization**. Warn that
connecting an enterprise *and* one of its organizations counts that
organization's costs twice; pick one level.

### 2. Choose the enterprise or organization

List what the signed-in GitHub CLI user can connect (read-only, needs no
Datadog credentials or token):

```bash
python3 <SKILL_DIR>/scripts/setup.py --list-targets
```

```json
{"status": "ok", "gh_login": "octocat", "organizations": ["acme"], "enterprises": null,
 "enterprises_note": "Listing enterprises needs the gh read:enterprise scope: gh auth refresh -h github.com -s read:enterprise"}
```

- `organizations` lists the organizations the `gh_login` user owns.
- `enterprises` lists the enterprises they administer or manage billing for. It
  is `null` when `gh` lacks the `read:enterprise` scope; `enterprises_note` then
  names the fix. If the user chose Enterprise, ask whether to run
  `gh auth refresh -h github.com -s read:enterprise` (it opens a browser) and
  rerun `--list-targets`, or let them type the enterprise slug instead.
- `gh_unavailable` → `gh` is missing or not signed in; ask for the enterprise
  slug or organization login directly.

Offer the matching list as choices with the host's interactive question tool
(the user can also type a slug or login). Confirm the `gh_login` is the GitHub account
they mean: the token must come from an owner or administrator of the target.
Never guess the target.

### 3. Name and tags

In one question form, gather values not already supplied:

- **Account name:** recommend one that names the target,
  such as `github-<target>`.
- **Tags (optional):** `key:value` tags to add to these costs, such as
  `team:platform`; no spaces or commas.

### 4. Approve and run

Before opening anything, tell the user what they will need to do: create a
GitHub personal access token on the page that opens (it is pre-filled with the
name, the permissions above, and, for organizations, the resource owner), and
paste it into a **separate terminal window** that the script opens. For an
organization the page presets a 365-day expiration; an enterprise's classic
token page defaults to 30 days. The terminal recommends **No expiration** (or,
for a classic token, at least 365 days) so costs keep flowing. Explain the
token requirements from Phase 0.

Then use the interactive question tool once for approval:

- **Title:** `Approve GitHub Costs integration setup`
- **Question:** ask this, with each step on its own line:

  > May I run the interactive setup? It will:
  >
  > - Open GitHub's token page, pre-filled for <TARGET>.
  > - Ask you to paste the token into a hidden prompt in a new terminal.
  > - Check with GitHub that the token can read <TARGET>'s billing.
  > - Register the named Datadog GitHub Costs account.
  >
  > The token is never visible to the agent, and will not be printed, passed as a command argument, stored in a file, or returned in output.
- **Approve option:** `Approve and open the secure token prompt`
- **Cancel option:** `Cancel without making changes`

After approval, run:

```bash
python3 <SKILL_DIR>/scripts/setup.py --account-name "<ACCOUNT_NAME>" --scope <enterprise|organization> --target "<TARGET>"
```

For example, an organization on the EU site with one tag:

```bash
DD_SITE=datadoghq.eu python3 <SKILL_DIR>/scripts/setup.py --account-name "github-acme" --scope organization --target "acme" --tag team:platform
```

Append `--tag <key:value>` once per tag. On Windows, use `python` instead of
`python3`. Pup uses its default session, and picks the Datadog site from
`DD_SITE` (default `datadoghq.com`): if the user's Pup session is on another
site, run the command with `DD_SITE` set to it (e.g. `datadoghq.eu`); if they
use a named Pup session (`pup auth login --org <name>`), also set the `DD_ORG`
environment variable to that session's name. Set them the way the shell expects: a
`NAME=value` prefix on POSIX shells, `$env:NAME="value";` in PowerShell, or
`set "NAME=value" &&` in cmd.exe. Do not detach the process or redirect its
input. Tell the user to switch to the new terminal when it appears — a
tmux window named `github-costs-token` when the session runs inside
tmux.

Run the command with the longest command timeout your tool allows (at least 10
minutes). The user may take up to 5 minutes to enter the token, and Datadog
requests have no client-side timeout. Killing the command during registration
leaves the outcome unknown.

The script always opens a new graphical terminal for token entry, because the
agent's own TTY may not be visible to the user; if it cannot, it fails instead
of prompting in place. Never ask the user to paste the token
into chat, and never pass it through a command argument, environment variable,
shell pipe, redirected input, or file.

## Deterministic behavior

Before asking for a token, the script validates Pup, returns an existing
account with the same name instead of creating one, and refuses a target that is
already connected. It checks the token with GitHub's billing API before
writing anything, sends one POST, and reconciles a failed POST by listing
accounts instead of retrying. The token stays in memory and is redacted from
all output.

## Results and recovery

Report the script's status and warnings without exposing credentials. Errors
print `{"status": "error", "error": {"reason": ..., "message": ...}}`; a
trimmed `complete` result looks like:

```json
{"status": "complete", "account": {"name": "github-acme", "target": "acme"},
 "cost_tag": "organization_name:acme",
 "links": {"costs": "https://app.datadoghq.eu/cost/summarize/overview?provider_id=GitHub%20Costs"}}
```

- **`complete`** → continue with
  [Getting the Most Out of Your Integration](#getting-the-most-out-of-your-integration).
- **`already_configured`** → an account with that name exists (`account.target`
  says what it reads); nothing changed. Offer a different name if they meant a
  new target.
- **`pup_cli_outdated`** → the installed Pup is older than v2 and cannot run this
  setup. Ask before upgrading it (see the Pup version preflight above), then rerun
  once the upgrade is done.
- **`target_already_connected`** → that enterprise or organization is already
  connected under `details.account.name`; nothing was written. Do not add it
  again: a second account would count those costs twice.
- **`duplicate_datadog_accounts`** → several accounts share that name. Do not
  create another; ask the user which one to keep, and stop.
- **`account_name_taken`** → while the token was being entered, another account
  with that account name appeared for a different target. If the POST was
  rejected, nothing was connected for the requested target; rerun with a
  different name. If it reports the POST succeeded, inspect the account list
  before rerunning.
- **`classic_token_required`** → an enterprise needs a classic token; the user
  pasted a fine-grained one. Rerun and create a classic token on the page that
  opens.
- **`invalid_github_token`** or **`github_token_rejected`** → nothing was
  written. Ask the user to create a fresh token and rerun.
- **`github_access_denied`** → GitHub refused the token for that target; relay
  the script's `message`. Usually the token lacks the permissions above, was
  created by someone who is not an owner/administrator, has the wrong resource
  owner, is awaiting organization approval, or the target slug or login is wrong.
- **`github_check_failed`** → GitHub could not be reached, rate-limited the
  check, or answered with a temporary error; nothing was written. Rerun shortly (and make sure the network
  allows `api.github.com`).
- **`terminal_launch_failed`** or **`terminal_launch_unsupported`** → no
  graphical terminal could be opened (headless, SSH, or container); nothing was
  written. Ask the user to rerun from a desktop session, or to connect it from
  the GitHub Costs integration tile.
- **`terminal_helper_not_connected`**, **`credential_entry_timeout`**, or
  **`credential_entry_cancelled`** → nothing was written. Ask whether to rerun.
- **`datadog_create_failed`** → Datadog rejected the request; nothing was
  written. Relay `details.pup_error`. A 403 usually means the user lacks the
  Integrations Manage (`manage_integrations`) permission.
- **`ambiguous_datadog_post`** → do not rerun, because the write may still land.
  Inspect the account list (read-only): report the account as created only if
  both its name and its `settings.enterprise_name` match the requested name and
  GitHub enterprise or organization. A `details.same_name_account` reads a
  different target, so it does not count. Otherwise keep the outcome ambiguous
  and send the user to the GitHub Costs integration tile to check the account.
- **`datadog_account_not_visible`** → Datadog accepted the account but it is not
  listed yet. Do not rerun; check the account list again later.
- Pup authentication failures → run `pup auth refresh`; if that fails, run
  `pup auth login` with the reported missing scopes.
- Any other status → relay the script's `message` and `reason`, and rerun once
  the cause is fixed. When the status says the write may have landed (as
  above), check the account list first.

## Getting the Most Out of Your Integration

After `complete`, give a short, enthusiastic headline that starts with 🎉, such
as "🎉 GitHub Costs is connected for <TARGET>!", then tell the user:

- GitHub costs appear in Cloud Cost Management (`links.costs`) under the
  **GitHub Costs** provider, typically within about 24 hours; GitHub's billing
  data is daily, so there is nothing to check sooner.
- They can filter to this connection with the `cost_tag` the script returned
  (`enterprise_name:<slug>` or `organization_name:<login>`), plus any tags they
  added.
- If the token has an expiration (365 days preset for an organization, 30 days
  by default for an enterprise's classic token), they should set a reminder to
  replace it before it expires. This skill does not update an existing
  account; manage it from the GitHub Costs integration tile in Datadog.
- For what the integration collects and how to configure it by hand, see the
  [GitHub Costs integration docs](https://docs.datadoghq.com/integrations/github-costs/).

Only describe what the script confirmed.
