skip to content

In GitHub Packages, a second private repository's workflow must install your organisation's private npm library and pull its image; how do you grant that without a personal token?

level: seniorimportance: should knowfreq 20%

answer

  1. the grant sits on the package
  2. the consumer's own job token
  3. not the same as connecting
  4. Maven is the exception

basics

~10 s

On each package's settings, use Manage Actions access to add the consuming repository with the Read role; its workflow then authenticates with its own GITHUB_TOKEN. Maven and Gradle packages lack this, being repository-scoped.

solid answer

~50 s

Each workflow's `GITHUB_TOKEN` speaks only for its own repository, so by default the `storefront` repository's job cannot read a private package linked to `billing`. For registries with granular permissions (Container, npm, NuGet, RubyGems) the fix sits **on the package**: in its settings, under **Manage Actions access**, add the `storefront` repository and choose the **Read** role. The consuming job then logs in to `ghcr.io` and `npm.pkg.github.com` with its own `GITHUB_TOKEN`; if the job declares a `permissions` block, it includes `packages: read`. This is different from connecting the package to a repository, which links it rather than granting access. The alternative, a classic token with `read:packages` stored as a secret, ties the pipeline to one person and is long-lived. Maven and Gradle packages are repository-scoped and have no such grant, so there the docs fall back to a classic token.

go deeper

for a junior

Recall that a workflow's job token reaches only its own repository's packages, and that another repository needs an explicit grant on the package.

for a middle

Explain how Manage Actions access differs from connecting a package, which roles it offers, and why the consuming job needs packages: read.

for a senior

Choose between a per-package grant and a classic token per registry, and spot the fork exposure and the Maven gap before they reach production.

for a principal

Decide how cross-repository package access is governed across many teams, who may grant it, and whether repository-scoped registries stay acceptable for shared libraries.

## The situation The `acme` organisation publishes two private packages from the `acme/billing` repository through **GitHub Packages**: an npm library `@acme/billing-client` and an image `ghcr.io/acme/billing-api`. A second private repository, `acme/storefront`, needs both in its CI: its workflow runs `npm ci`, which installs the library, and its integration tests pull the image. The first attempt fails. The storefront job's `GITHUB_TOKEN` is an installation token whose permissions are **limited to the repository containing the workflow**. The packages are linked to `acme/billing`, so storefront's token has no read access to them. ## The two ways to give a workflow access | | Manage Actions access grant | Classic personal token in a secret | |---|---|---| | where it is set | on each package, naming the consuming repository | in the consuming repository's secrets | | credential the job uses | its own `GITHUB_TOKEN` | a person's token with `read:packages` | | lifetime | per job | until it expires or is revoked | | breaks when someone leaves | no | yes, if it was their token | | registries | Container, npm, NuGet, RubyGems | every registry, including Maven and Gradle | The grant also has a quieter benefit: GitHub's billing counts package downloads authenticated with `GITHUB_TOKEN` as GitHub Actions downloads, which do not use up the owner's data transfer allowance. How that allowance works belongs to the material on package billing. ## Granting the consuming repository a role For packages scoped to a user or organisation, GitHub's documentation says that, apart from workflows in a linked repository that inherits access, a workflow gets access only when the repository where it is stored has been given explicit access. On each package: 1. open the package's **Package settings**; 2. under **Manage Actions access**, choose **Add repository** and pick `acme/storefront`; 3. set its **Role** to **Read**, which allows downloading the package and reading its metadata (Write would also allow uploading new versions). The consuming job then needs nothing stored. It logs in to `ghcr.io` with `GITHUB_TOKEN` and the triggering user as username, and points npm's auth line for `npm.pkg.github.com` at the same token. If the job declares a `permissions` block, that block must include `packages: read`, because a job's token gets only what the block lists. Three details matter in review: - The repository you add **does not have to be the package's source repository**, and you can add several. - **Manage Actions access is not connecting.** Connecting a package to a repository links it, so the package page shows the repository's README and the package can inherit that repository's access. Adding a repository under Manage Actions access only grants that repository's workflows a role. - **A public repository is a risk.** If you grant a public repository access to private packages, forks of that repository may be able to read them too. The same grant also lets Dependabot pull the package for that repository without a personal token. ## Where the grant does not exist: Maven and Gradle The Apache Maven and Gradle registries support only **repository-scoped permissions**. A Maven artifact published into `acme/billing` always follows that repository's permissions, and there is no package-level Manage Actions access to edit. For a workflow in another private repository that its `GITHUB_TOKEN` cannot reach, GitHub's documentation directs you to a **personal access token (classic)** with `read:packages`, stored as a secret. If the library also exists as a Maven artifact, either accept that token, created narrowly and owned by an account the team controls, or publish what other repositories consume into an npm or container package that supports the grant. ## Why not just use a token everywhere A classic token with `read:packages` works for every registry, which is its appeal. Its costs are the ones a platform team inherits later: - it is **long-lived** and sits in a secret every workflow in the repository can read; - it acts as a **person**, so access breaks when that person leaves or loses the role; - created with `write:packages` in the web form, it typically carries the broad `repo` scope, which far exceeds pulling a package. GitHub's guidance for registries with granular permissions is explicit: workflows should use `GITHUB_TOKEN` rather than a personal token.

  • In GitHub Packages, after you add acme/storefront under Manage Actions access, its job still gets denied pulling the image. What do you check?
    First, whether the job declares a `permissions` block without `packages: read`, which leaves its `GITHUB_TOKEN` with no packages access. Then whether the grant was made on the right package, since each package carries its own list, and whether the login used `GITHUB_TOKEN` rather than an old personal token secret that no longer has access.
  • Why is granting a public repository Read access to a private package in GitHub Packages risky?
    GitHub's documentation warns that if a public repository is granted access to private packages, forks of that repository may be able to access them. A workflow running from a fork could then download the private package, so grant only private or internal repositories that you control.
  • In GitHub Packages, the storefront repository also needs the billing team's Maven artifact. Can Manage Actions access cover it?
    No. Maven and Gradle packages support only repository-scoped permissions and always follow the repository they were published into, so there is no package-level grant to add storefront to. The documented route for a workflow in another private repository is a classic personal token with `read:packages`, kept narrowly scoped and owned by an account the team controls.

Manage Actions access is like putting a named team on the guest list at one particular door: the team shows its own badge and gets in, and nobody lends out a personal house key that opens every door they own.

  • Connecting the package to the storefront repository is how you grant its workflow access.
  • Give the consuming repository a classic token with repo scope; it is simplest.
  • A workflow's GITHUB_TOKEN can read every private package in its organisation by default.
  • Manage Actions access works the same way for Maven packages as for images.
  • Granting a public repository access to private packages exposes nothing further.