Ginkgo - GitHub Actions Carbon Estimator

Estimate the environmental impact of GitHub Actions for your entire organization.

About

Ginkgo helps organizations understand and track the carbon footprint of their GitHub Actions workflows by analyzing billing data and applying carbon estimation models. For measuring carbon emissions per workflow, look at eco-ci-energy-estimation. The billing data can be retrieved using the GitHub API.

Features

• Calculates estimated carbon emissions for GitHub Action based on billed usage
• Fetches GitHub Actions billing data NOT YET
• Runs as a GitHub Action in your workflows or on the command line NOT YET

Output

Ginkgo takes as input a JSON usage report and enriches it by adding two fields to the usageItems:

• energy_usage_wh
• co2eq_g

Here is what an enriched usageItem looks like

{
  "date": "2026-02-01T04:48:44Z",
  "product": "actions",
  "sku": "Actions Linux",
  "quantity": 91,
  "unitType": "Minutes",
  "pricePerUnit": 0.006,
  "grossAmount": 0.546,
  "discountAmount": 0.546,
  "netAmount": 0,
  "organizationName": "DigitalPebble",
  "repositoryName": "spruce",
  "energy_usage_wh": 7.592,
  "co2eq_g": 2.672
}

Build

Prerequisite: install a Rust toolchain locally.

cargo install --path .

CLI Usage

Ginkgo - GitHub Actions Carbon Estimator

Usage: ginkgo [OPTIONS]

Options:
  -f, --file <FILE>                  Path to a local billing JSON file (instead of fetching from GitHub API)
  -t, --token <TOKEN>                GitHub token with billing:read permission [env: INPUT_GITHUB_TOKEN]
  -o, --organization <ORGANIZATION>  GitHub organization name [env: INPUT_ORGANIZATION]
  -O, --output <OUTPUT>              Path where the carbon estimate report will be saved [env: INPUT_OUTPUT_PATH] [default: ./carbon-estimate.json]
  -h, --help                         Print help
  -V, --version                      Print version

From a local billing file

With the GH CLI installed:

ORG=enter_org_here
gh api /organizations/$ORG/settings/billing/usage > gh_bill.json
ginkgo --file gh_bill.json

This will produce an enriched version of the usage reports in ./carbon-estimate.json. You can specify a different output with -O output_file.

As a filter (stdin → stdout)

When called with no arguments, Ginkgo reads a billing JSON from stdin and writes the enriched result to stdout, making it easy to compose with other tools:

ORG=enter_org_here
gh api /organizations/$ORG/settings/billing/usage | ginkgo

Or to save to a file:

gh api /organizations/$ORG/settings/billing/usage | ginkgo > carbon-estimate.json

Error messages are written to stderr; stdout contains only the JSON output.

Retrieve and enrich the usage reports from the GitHub API

WORK IN PROGRESS you need to specify both the name of your organization and a token. This can be done on the command line or as an environment variable.

ginkgo --token ghp_... --organization your-org

The output is written to the path specified by --output (defaults to ./carbon-estimate.json).

GitHub Action Usage

WORK IN PROGRESS

- uses: DigitalPebble/ginkgo@main
  with:
    github_token: ${{ secrets.BILLING_TOKEN }}
    organization: your-org
    output_path: carbon-estimate.json  # optional

Input	Required	Default	Description
github_token	Yes	-	GitHub token with billing:read permission
organization	Yes	-	GitHub organization name
output_path	No	carbon-estimate.json	Path where the report will be saved

Required Permissions

The GitHub token must have:

• billing:read - To access organization billing information

You can create a fine-grained personal access token with only the billing:read permission scoped to your organization.

Carbon Estimation Methodology

The energy consumption estimates are taken from BoaviztAPI, the carbon intensity factor is an average for the US in 2024 from Ember. The PUE is as reported by Microsoft for the datacentres in America in 2025.

License

Apache License 2.0

Credits

Developed by DigitalPebble. Please get in touch if you need our help with GreenOps or digital sustainability in general.