skip to content

In GitHub Packages, how do granular package permissions differ from repository-scoped ones, and when does a package inherit its linked repository's access?

level: middleimportance: must knowfreq 34%

answer

  1. two permission families of registries
  2. which registries stand apart from repositories
  3. link before or after the first publish
  4. removing inheritance unlocks package roles

basics

~20 s

Container, npm, NuGet and RubyGems packages belong to an account and can carry their own Read, Write and Admin roles; Maven and Gradle packages always follow their repository. A linked package inherits repository access until you remove that inheritance.

solid answer

~50 s

GitHub Packages has two permission models. Registries with **granular permissions** — the Container registry, npm, NuGet and RubyGems — scope a package to a personal account or an organization, so the package carries its own **Read**, **Write** and **Admin** roles for people, teams and repositories. **Apache Maven and Gradle** support only repository-scoped permissions: the package is published into a repository and always follows that repository's access. For a granular package, *when* you link matters: linked at first publish (for an image, through the `org.opencontainers.image.source` label), it inherits the repository's access permissions by default and that repository's workflows can use it; connected later from the package page, it keeps its existing permissions unless you opt in. To assign roles on the package itself you remove the inherited permissions, and an organization owner can switch automatic inheritance off for new packages.

go deeper

for a junior

Recall the split: Container, npm, NuGet and RubyGems packages can have their own roles, while Maven and Gradle packages always follow the repository.

for a middle

Explain that inheritance depends on when the link is made, that editing package roles requires removing inheritance, and what Read, Write and Admin each allow.

for a senior

Show you would audit current access before switching a package off inheritance, since the switch overwrites existing permissions, and keep workflow access working afterwards.

for a principal

Weigh inheritance, which keeps one source of truth in repository access, against granular roles, which let a shared package serve many repositories without widening repository access.

## Two permission models, decided by the registry GitHub Packages hosts several registries, and they do not share one access model. Which model a package gets is decided by the **registry** it lives in, not by a setting you pick later. | Registry | Permission model | Where the package lives | |---|---|---| | Container registry (`ghcr.io`) | Granular | Scoped to a personal account or organization | | npm | Granular | Scoped to a personal account or organization | | NuGet | Granular | Scoped to a personal account or organization | | RubyGems | Granular | Scoped to a personal account or organization | | Apache Maven | Repository-scoped only | Published into a repository | | Gradle | Repository-scoped only | Published into a repository | A **repository-scoped** package always inherits the permissions of the repository it was published to. If you can read the repository you can download the package; if you administer the repository you can delete it. There is nothing to configure on the package itself, which is simple but inflexible: you cannot give a team write access to the Maven artifact without giving it to the repository. A **granular** package is a free-standing resource owned by an account. It can exist with no repository at all, and it can have its own visibility and its own role assignments. ## The three package roles When a granular package manages its own access, it uses three roles: | Role | What it allows | |---|---| | **Read** | Download the package and read its metadata | | **Write** | Upload and download versions; read and write metadata | | **Admin** | Everything Write allows, plus delete the package, manage it and grant package permissions | The person who publishes a package gets **Admin** automatically, and when the package is published into an organization, anyone with the organization's `owner` role is an admin of it too. On a package scoped to a personal account you can grant roles to any person; on an organization package you can grant them to people or teams in the organization, and a private or internal organization package can only be shared with that organization's members and teams. ## What linking a repository actually does A granular package can be **linked** (connected) to a repository. The link shows the repository's README on the package page and, more importantly, can make the package **inherit the repository's access permissions**. Whether it does depends on the order of events: 1. **Linked before the first publish** — for example an image built with the `org.opencontainers.image.source` label pointing at the repository. The package inherits the repository's access permissions by default, and GitHub Actions workflows in that repository automatically get access to it. 2. **Connected after publishing**, from the package's settings page. The package **keeps its existing permissions** and inherits nothing unless you explicitly select inheritance. 3. **Organization default switched off** — an organization owner can deselect *Inherit access from source repository* under the organization's default package settings, so new packages scoped to that organization do not inherit automatically. Package admins can still turn inheritance on or off per package. The access-control guide is precise that inheritance covers access permissions and not visibility, so check a package's visibility on the package itself rather than assuming it follows the repository. ## Moving from inherited to granular access While a package inherits, you change who can reach it by changing the **repository's** permissions; the package's own role list is not where you edit access. To manage roles on the package, a package admin deselects **Inherit access from repository (recommended)** in the package settings. Two consequences matter in practice: - the documentation warns that **changing how a package gets its access permissions overwrites any existing permissions**, so list who and which repositories rely on access before you flip it; - after the switch, the linked repository's workflows keep access only if you grant that repository a role on the package. Granting a repository's workflows a role through the package's **Manage Actions access** section is a different action from connecting the package to that repository; the material on registries and authentication covers that cross-repository flow. ## Traps interviewers listen for - Assuming every registry supports per-package roles — Maven and Gradle do not. - Believing that connecting an existing package to a repository silently hands the repository's collaborators access. - Trying to edit package roles while inheritance is still on, then wondering why nothing changes. - Forgetting that disabling automatic inheritance at the organization level affects **new** packages only. - Treating repository admin as the only path to package admin, when the publisher and organization owners are admins as well.

  • In GitHub Packages, you connect an already-published image to a repository from the package page. Do the repository's collaborators now have access?
    Not automatically. Connecting a published package from its settings page keeps the package's existing permissions; it inherits the repository's access only if you explicitly select the inherit option. Automatic inheritance happens when the link exists at first publish, such as through the image's source label, and the organization has not disabled it.
  • What happens to existing grants when you switch a GitHub Packages package between inherited and granular access?
    The documentation warns that changing how a package gets its access permissions overwrites any existing permissions. Inventory the people, teams and repositories that currently reach the package, make the switch, then re-grant the roles they need; otherwise workflows that relied on inheritance lose access at that moment.
  • Can a GitHub Packages Maven package give one team write access that the repository does not?
    No. Apache Maven and Gradle registries support only repository-scoped permissions, so the package always inherits the repository's permissions. To change who can publish it you change repository access; per-package roles exist only in the Container, npm, NuGet and RubyGems registries.

  • Every GitHub Packages registry supports per-package roles, including Maven and Gradle.
  • Connecting a published package to a repository automatically copies the repository's access.
  • You can edit a package's own roles while it still inherits repository access.
  • Disabling automatic inheritance in the organization changes every existing package.
  • Only repository admins can ever be admins of a package.
  • Manage Actions access and connecting a repository are the same setting.