{"id":15368967,"url":"https://github.com/davelosert/gh-billing-report","last_synced_at":"2025-04-15T13:27:23.114Z","repository":{"id":244825400,"uuid":"744487544","full_name":"davelosert/gh-billing-report","owner":"davelosert","description":"A command line tool to use the new GitHub Enterprise Billing usage API to easily export usage to an Excel-File.","archived":false,"fork":false,"pushed_at":"2025-03-17T12:27:52.000Z","size":393,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T20:35:53.989Z","etag":null,"topics":["gh-cli"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davelosert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-17T12:00:27.000Z","updated_at":"2025-02-17T14:10:20.000Z","dependencies_parsed_at":"2024-10-22T11:38:08.380Z","dependency_job_id":null,"html_url":"https://github.com/davelosert/gh-billing-report","commit_stats":{"total_commits":38,"total_committers":2,"mean_commits":19.0,"dds":0.1578947368421053,"last_synced_commit":"7e79ebb246b3c31b4a77b2ec1ab5daca67a40fee"},"previous_names":["davelosert/gh-billing-report"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davelosert%2Fgh-billing-report","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davelosert%2Fgh-billing-report/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davelosert%2Fgh-billing-report/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davelosert%2Fgh-billing-report/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davelosert","download_url":"https://codeload.github.com/davelosert/gh-billing-report/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249078904,"owners_count":21209271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gh-cli"],"created_at":"2024-10-01T13:33:26.629Z","updated_at":"2025-04-15T13:27:23.095Z","avatar_url":"https://github.com/davelosert.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GH Billing Report\n\nA command line tool to use GitHub's new [Enhanced Enterprise Billing Usage Report APIs](https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/billing?apiVersion=2022-11-28#get-billing-usage-report-for-an-enterprise) to export an Excel-Report with the usage for a given Billing-Cycle, grouped and aggregated by organization.\n\n![Screenshot of an Excel File containing a Billing Report by Organization](./docs/images/org-report.png)\n\n## Getting Started\n\n### Using the GH Extension\n\nThe easiest way to use this tool is to install it as a [GitHub CLI](https://cli.github.com/) Extension.\n\n1. Install the extension:\n\n    ```bash\n    gh extension install davelosert/gh-billing-report\n    ```\n\n2. Create a [classical GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with the scopes `manage_billing:enterprise` and `read:enterprise`\n\n3. Generate the report:\n\n    ```bash\n    gh billing-report --enterprise my-enterprise --github-token $GITHUB_TOKEN\n    ```\n\n    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](#options) for more information on how to customize the report.\n\n### Using the repo directly\n\nYou can also clone this repo and run the following commands:\n\n```bash\ngo run . --enterprise my-enterprise --github-token $GITHUB_TOKEN\n```\n\n\u003e [!NOTE]\n\u003e This requires you to have [Go](https://golang.org/) \u003e1.21.5 installed on your machine.\n\n## Options\n\nAll options can be set as flags via the command line:\n\n```bash\ngh billing-report --github-token \u003cgithub-token\u003e \\\n  --enterprise \u003centerprise-slug\u003e \\\n  --year \u003cyear\u003e \\\n  --month \u003cmonth\u003e \\\n  --billing-cycle \u003cbilling-cycle\u003e \\\n  --report-path \u003creport-path\u003e\n```\n\nThe `GITHUB_TOKEN` will be automatically read from the Environment-Variable, but can be overwritten using the `--github-token` flag.\n\n| Option                            | Description                                                         | Default Value | Environment Variable |\n| --------------------------------- | ------------------------------------------------------------------- | ------------- | -------------------- |\n| `--github-token \u003cgithub-token\u003e`   | Github token, see below for permissions                             | None          | `GITHUB_TOKEN`       |\n| `--enterprise \u003centerprise-slug\u003e`  | Enterprise Slug to get the data from                                | None          | None                 |\n| `--year \u003cyear\u003e`                   | Specify the year, e.g. 2024                                         | Current year  | None                 |\n| `--month \u003cmonth\u003e`                 | Specify the month, e.g. 1                                           | Current month | None                 |\n| `--billing-cycle \u003cbilling-cycle\u003e` | First day of your billing cycle (see below for further information) | 1             | None                 |\n| `--report-path \u003creport-path\u003e`     | Directory where the report will be saved                            | `./reports`   | None                 |\n\n### Billing Cycle\n\nBy default, the generated report covers an entire calendar month (e.g., `1st of January` to `31st of January`).\n\nYou 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\n\n- from the specified **billing cycle day of the input month**\n- to the day **before the same billing cycle day of the following month**\n\nIf 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:\n\n| Input                                      | Report Period                                     |\n| ------------------------------------------ | ------------------------------------------------- |\n| `--year 2024 --month 1 --billing-cycle 1`  | `1st of January 2024` to `31st of January 2024`   |\n| `--year 2024 --month 1 --billing-cycle 15` | `15th of January 2024` to `14th of February 2024` |\n| `--year 2024 --month 2 --billing-cycle 30` | `1st of March 2024` to `29th of March 2024`       |\n\n\u003e [!IMPORTANT]\n\u003e Please note that all cutoff dates are in UTC. Therefore, a report with `--year 2024 --month 1 --billing-cycle 15` will include all usage data from `15th of January 2024 00:00:00 UTC` to `14th of February 2024 23:59:59 UTC`.\n\n### Github Token Permissions\n\nYou need to create a [classical GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with the following Scopes:\n\n- `manage_billing:enterprise`\n- `read:enterprise`\n\n## Output\n\nCurrently, the output is an Excel file containing the two sheets:\n\n- **Usage by Organization**: Contains the aggregated usage by organization where:\n  - **Gross Amount**: The gross amount of the usage\n  - **Discount**: The discount applied to the usage\n  - **Net Amount**: The net amount of the usage - this is what you will be billed\n- **Detail Usage**: Contains all usage items of the billing cycle you specified so you can drill down into the data\n    ![Screenshot of the Detail Usage Sheet](./docs/images/usage-details.png)\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavelosert%2Fgh-billing-report","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavelosert%2Fgh-billing-report","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavelosert%2Fgh-billing-report/lists"}