In GitHub Packages, why might private npm downloads start counting against data-transfer allowance after CI moves to self-hosted runners?
answer
- storage and transfer, private only
- how GitHub recognises an Actions download
- hosted versus self-hosted
- which token the job logs in with
basics
~10 sGitHub Packages bills private storage and outbound transfer. Downloads are free when a workflow logs in with GITHUB_TOKEN; with a personal access token they are free on GitHub-hosted runners but billed on self-hosted ones.
solid answer
~40 sGitHub Packages meters two things for **private** packages: **storage**, accrued hourly and charged to the repository owner, and **data transfer** for downloads, also charged to the owner; public packages and inbound transfer are free. Downloads by GitHub Actions don't count against the hosting repository's transfer, and GitHub recognises them by the job logging in with `GITHUB_TOKEN`. The billing table spells out the edge: `GITHUB_TOKEN` is free on hosted and self-hosted runners, while a **personal access token is free on GitHub-hosted runners but paid on self-hosted ones**. So a pipeline that moved to self-hosted runners and still authenticates with a stored personal token starts consuming the owner's allowance. Switch it to `GITHUB_TOKEN`, granting the consuming repository read on the package, and the transfer stops counting.
go deeper
Remember that public packages are free and private ones use storage and data transfer from the repository owner's allowance.
Explain how GitHub recognises an Actions download by the GITHUB_TOKEN login and why storage counts every version you keep.
Diagnose a transfer spike from runner type and credential, fix it with GITHUB_TOKEN and package read access, and add alerts and budgets.
Shape publishing and retention so storage stays bounded, and keep CI authentication on GITHUB_TOKEN as runners move between hosted and self-hosted.
## What GitHub Packages bills GitHub Packages billing has two meters, and both apply only to **private** packages: - **Storage** — the total file size of the package versions you keep. Charges accrue continuously based on hourly usage, expressed as GB-months, and the accrued total resets at the start of each billing cycle. - **Data transfer** — bytes downloaded from the registry. The included quota resets each billing cycle, and transfer is rounded to the nearest GB at month end. What is free: | Usage | Billed? | |---|---| | Anything for **public** packages | Free | | Data transferred **in** from any source (publishing) | Free | | Container registry storage and bandwidth | Free as of October 2026, with at least a month's notice promised before any change | | Actions downloads authenticated with `GITHUB_TOKEN` | Free | Usage lands on the **repository owner's** account: publishing a private package adds to the owner's storage, and downloading it adds to the owner's transfer. Anyone with write access can publish without increasing their personal account's usage. ## How GitHub recognises an Actions download The billing rules exempt package downloads made by GitHub Actions from the hosting repository's transfer. GitHub decides that a download comes from Actions **when the job logs in to GitHub Packages with `GITHUB_TOKEN`**. The documented matrix: | Credential in the job | GitHub-hosted runner | Self-hosted runner | |---|---|---| | `GITHUB_TOKEN` | Free | Free | | Personal access token | Free | **Paid** | That is the whole explanation for the scenario. While the builds ran on GitHub-hosted runners, a pipeline that installed private npm packages with a stored personal access token cost nothing in transfer. After the move to self-hosted runners, the same token makes every install count against the owner's data-transfer quota — and busy CI installs the same dependencies many times a day. ## Fixing it 1. **Switch the job to `GITHUB_TOKEN`** for installing from GitHub Packages. The exact client configuration belongs to the material on registries and authentication; the billing point is which credential the login uses. 2. **Grant the consuming repository read access** on each package it installs. A private package can be downloaded by a workflow only if the workflow's repository has been given read permission on it, unless the package inherits access from that same repository. 3. **Watch the usage**: GitHub sends email notifications when included Packages usage reaches 90% and 100% during a billing period, and budgets can cap spending. ## Storage, the slower leak Storage grows with every version you keep. The billing page's own example: publish a 500 MB private package, then publish a fixed 500 MB version without deleting the first, and the owner now uses 1 GB. Points that follow: - storage counts **every retained version**, so a pipeline publishing snapshots on every merge grows storage steadily; - the included storage is **shared with GitHub Actions artifacts**, so large workflow artifacts and package versions draw on one allowance; - storage is averaged over the month in GB-hours, so a short spike costs less than a sustained one. ## When the quota runs out If the account has **no valid payment method**, usage is **blocked** once the included quota is used up — installs start failing rather than producing a bill. With a payment method on file, usage beyond the quota is billed, subject to any budgets the account has set. Plan allowances differ by GitHub plan and change over time, so read the current billing page rather than memorising sizes or prices. ## Misconceptions - "Publishing uses transfer." Inbound transfer is free. - "All CI downloads are free." Only when GitHub can see they come from Actions via `GITHUB_TOKEN`, or with a personal token on GitHub-hosted runners. - "The developer who publishes pays." Usage lands on the repository owner. - "Container images are billed like npm packages." Container registry storage and bandwidth are currently free.
- In GitHub Packages, a team republishes a 500 MB private package as a new version without deleting the old one. What happens to storage?Storage counts each retained version, so the repository owner now uses about 1 GB. Storage is metered hourly and averaged into GB-months over the billing cycle, so deleting versions you no longer need is what brings it down.
- In GitHub Packages, what happens when private usage exceeds the included quota and the account has no payment method?Usage is blocked once the quota is used up, so installs and publishes start failing rather than generating charges. With a payment method on file, excess usage is billed instead, within any budgets the account has set.
- Publishing a package consumes the data-transfer allowance.
- Every download from a CI runner is free, whatever token it uses.
- The developer who publishes a package pays for its storage.
- Container registry images are billed exactly like private npm packages.
- Running out of quota without a payment method just produces a bill later.