A command line tool to use GitHub's new Enhanced Enterprise Billing Usage Report APIs to export an Excel-Report with the usage for a given Billing-Cycle, grouped and aggregated by organization.

The easiest way to use this tool is to install it as a GitHub CLI Extension.

1. Install the extension:

   gh extension install davelosert/gh-billing-report

2. Create a classical GitHub PAT with the scopes manage_billing:enterprise and read:enterprise

3. Generate the report:

   gh billing-report --enterprise my-enterprise --github-token $GITHUB_TOKEN

   This will generate a report for the current running calendar month and save it to the ./reports folder of the current working directory. See the Options Section below for more information on how to customize the report.

You can also clone this repo and run the following commands:

go run . --enterprise my-enterprise --github-token $GITHUB_TOKEN

All options can be set as flags via the command line:

gh billing-report --github-token <github-token> \
  --enterprise <enterprise-slug> \
  --year <year> \
  --month <month> \
  --billing-cycle <billing-cycle> \
  --report-path <report-path>

The GITHUB_TOKEN will be automatically read from the Environment-Variable, but can be overwritten using the --github-token flag.

By default, the generated report covers an entire calendar month (e.g., 1st of January to 31st of January).

You can customize this range using the --billing-cycle option, which sets the start day of your billing cycle. The report will then cover the period

• from the specified billing cycle day of the input month
• to the day before the same billing cycle day of the following month

If the given billing cycle day does not exist in the given month, the first day of the next month will be used. See the following examples:

You need to create a classical GitHub PAT with the following Scopes:

• manage_billing:enterprise
• read:enterprise

Currently, the output is an Excel file containing the two sheets:

• Usage by Organization: Contains the aggregated usage by organization where:
  • Gross Amount: The gross amount of the usage
  • Discount: The discount applied to the usage
  • Net Amount: The net amount of the usage - this is what you will be billed
• Detail Usage: Contains all usage items of the billing cycle you specified so you can drill down into the data

This project is licensed under the MIT License.