Onboard GitHub Co-Pilot to CloudHiro with a read-only GitHub App
Create a GitHub App owned by your organization so CloudHiro can read billing, Copilot, and optional Actions usage signals without access to source code, issues, pull requests, or write permissions.
You need to be an organization owner on GitHub. A GitHub App belongs to an installation, not a person, so there is no user token to rotate and access keeps working when staff change.
Send these details through the secure channel agreed with your CloudHiro contact. Never email the .pem file in plain text.
| Permission | Level | Required | Data it unlocks | Endpoint |
|---|---|---|---|---|
| Organization: Administration | Read-only | Yes | Platform spend, spend budgets, Actions cache usage | GET /organizations/{org}/settings/billing/usage |
| Organization: GitHub Copilot Business | Read-only | Only if you use Copilot | Copilot seats and last activity | GET /orgs/{org}/copilot/billing/seats |
| Organization: Organization Copilot Metrics | Read-only | Only if you use Copilot | Per-user daily Copilot usage | GET /orgs/{org}/copilot/metrics/reports/users-1-day |
| Repository: Actions | Read-only | Optional | Workflow run durations and long-running workflows | GET /repos/{org}/{repo}/actions/runs |
CloudHiro does not request other repository permissions, account permissions, write access, webhooks, or event subscriptions.
- Go to your organization settings, then Developer settings, GitHub Apps, New GitHub App.
- Use a clear app name, for example
CloudHiro. - Set the Homepage URL to
https://cloudhiro.com. - Uncheck Active under Webhook. The app only makes outbound calls.
- Leave callback URL and Request user authorization empty or unchecked.
Under Organization permissions, set exactly these permissions:
- Administration - Read-only
- GitHub Copilot Business - Read-only, skip if you do not use Copilot
- Organization Copilot Metrics - Read-only, skip if you do not use Copilot
Optional: for the long-running workflow report, set Repository permissions, Actions to Read-only. Metadata read-only is added automatically. Leave every other permission at No access.
Administration is the only permission GitHub exposes for billing data, and read-only grants no write access.
Copilot must be enabled on the organization, otherwise Copilot calls return 404 regardless of permissions.
The Copilot usage report also requires the Copilot usage metrics policy to be enabled under Settings, Copilot, Policies.
- Under Where can this GitHub App be installed, choose Only on this account, then create the app.
- Copy the App ID from the app settings page.
- Scroll to Private keys and generate a private key. A .pem file downloads; treat it like a password.
- In the app's left menu, choose Install App, then Install next to your organization.
- Choose Only select repositories and select none, or choose All repositories. CloudHiro never reads repository contents.
- Click Install. The page URL ends with
/installations/<number>; that number is the Installation ID.
Send these four items to your CloudHiro contact through the agreed secure channel:
- Organization name
- App ID
- Installation ID
- Private key (.pem file)
What CloudHiro can and cannot do
CloudHiro can read billing and spend data, budgets, workflow run durations, Copilot seat assignments and usage, and Actions cache usage.
CloudHiro cannot read source code, issues, pull requests, logs, or artifacts; cannot change settings, budgets, billing configuration, or seats; and cannot create or delete anything in your organization.
To revoke access, uninstall or delete the GitHub App from GitHub. Access stops immediately with no coordination required.