In GitHub Packages, why can a workflow pushing to ghcr.io with GITHUB_TOKEN and packages: write still be denied, and how does org.opencontainers.image.source help?
answer
- the job token speaks for one repository
- a CLI push is not linked
- a label set before the first push
- linking differs from granting access
basics
~20 sGITHUB_TOKEN can only push to packages its repository may write, and an image first pushed from the command line is not linked to any repository; setting the org.opencontainers.image.source label before publishing links the image so the workflow's repository gets access.
solid answer
~40 s`GITHUB_TOKEN` acts for the workflow's repository, so GitHub Packages lets it write only to packages that repository has access to. Publishing a new image from a workflow links it to that repository automatically. But an image someone first pushed from the command line is **not linked**, even if its name matches the repository, and GitHub's documentation says the workflow token then has no permission to push to that existing package. The fix for that package is to grant the workflow's repository a role under **Manage Actions access** in the package settings, or to connect it to the repository and choose to inherit its access. To prevent it, add `LABEL org.opencontainers.image.source=https://github.com/acme/api` to the Dockerfile: a package linked this way before publishing inherits the repository's access, and the repository's workflows get access with it.
code
bash · 4 linesdocker build \
--label "org.opencontainers.image.source=https://github.com/acme/api" \
-t ghcr.io/acme/api:1.4.0 .
docker push ghcr.io/acme/api:1.4.0go deeper
Recall that a workflow publishes with GITHUB_TOKEN and packages: write, and that the org.opencontainers.image.source label points an image at its repository.
Explain why a command-line push leaves the package unlinked, and how linking at publish time, connecting later and Manage Actions access differ.
Diagnose a denied workflow push by asking which repository the token speaks for and what role that repository holds on the existing package, then fix it without a personal token.
Set a rule for how every image in the organisation is first published and linked, so no package is born unlinked and every pipeline runs without personal tokens.
## Why a workflow should publish with GITHUB_TOKEN Every GitHub Actions job receives a `GITHUB_TOKEN`, an installation access token for the GitHub App that Actions installs on the repository. For **GitHub Packages** it has three properties a personal token lacks: - it is **issued per job and expires with it**, so there is no long-lived secret to store, leak or rotate; - it acts for **the repository that contains the workflow**, not for a person, so it does not stop working when someone leaves; - it carries the permissions the job's `permissions` key grants; to publish, the job declares `packages: write` (and `contents: read` to check out the code). For the registries with granular permissions (Container, npm, NuGet, RubyGems), GitHub's documentation strongly recommends replacing any personal token in a workflow with `GITHUB_TOKEN`. A personal access token (classic) with `write:packages` also tends to drag in the broad `repo` scope, which a compromised runner could misuse. How the `permissions` key itself works belongs to the GitHub Actions material; here the point is which **package** the token may write. ## What the job token may write The job token is a repository identity, so the question is always: does **this repository** have write access to **this package**? The documented defaults: | Situation | Can the workflow's `GITHUB_TOKEN` push? | |---|---| | the workflow publishes a brand-new image | yes; the image is linked to the workflow's repository automatically | | the image is linked to the repository and inherits its access | yes; workflows in the linked repository get access | | the image was first pushed from the command line and never connected | no; the token has no permission on that existing package | | the repository was added under Manage Actions access with the Write role | yes, whichever repository holds the source | The third row is the classic surprise. A developer runs `docker push ghcr.io/acme/api:dev` from a laptop with a classic token. That creates the package `acme/api` in the `acme` organisation, **unlinked**. A command-line push is not linked to a repository by default, even when the image name matches a repository such as `acme/api`. When the team later moves publishing into a workflow in the `acme/api` repository, the push is denied although the job has `packages: write`. ## The fixes, and which one applies 1. **Grant the workflow's repository a role on the package.** In the package settings, under **Manage Actions access**, use **Add repository** and give `acme/api` the Write role. This is the direct fix for a package that already exists. It is not the same as connecting the package to a repository: it grants access and changes nothing about the package page. 2. **Connect the package to the repository.** **Connect repository** on the package page links it, but a package connected after publishing **keeps its existing access permissions** and inherits the repository's only if you explicitly choose that. 3. **Label the image before it is first published.** A package inherits the linked repository's access automatically only if the link exists when the package is published, which is exactly what the label provides. ## The label `org.opencontainers.image.source` is a pre-defined OCI annotation key, and the Container registry reads it to link an image to a repository: ```bash docker build \ --label "org.opencontainers.image.source=https://github.com/acme/api" \ -t ghcr.io/acme/api:1.4.0 . ``` The same can be written as a `LABEL` line in the Dockerfile, so every build, from a laptop or from CI, carries the link. GitHub's documentation recommends the label for both purposes: to connect a repository when publishing from the command line, and to make sure the workflow's `GITHUB_TOKEN` has the permissions it needs. The registry also reads `org.opencontainers.image.description` (up to 512 characters) and `org.opencontainers.image.licenses` (an SPDX identifier) for the package page, but neither links anything. ## What linking does not do - It is not a **visibility** control: whether the package is private, internal or public is a separate package setting. - An organisation can switch off **automatic inheritance** for new packages, in which case even a labelled image needs an explicit Actions access grant. - It gives access to the **linked** repository's workflows only. A different repository that needs to pull the image needs its own grant. The rules on inheritance, visibility and deleting packages belong to the material on package access and retention.
- In GitHub Packages, does connecting an already-published image to a repository give that repository's workflows access?Not by itself. A package connected from its settings page after publishing keeps its existing access permissions and inherits the repository's only if you explicitly select that option. Automatic inheritance happens when the link exists at publish time, for example through the `org.opencontainers.image.source` label. Granting the repository a role under Manage Actions access is the explicit alternative.
- In GitHub Packages, why does the documentation push teams to replace a classic personal token in an image-publishing workflow with GITHUB_TOKEN?Because the classic token is long-lived, belongs to a person and, when created with `write:packages` in the web form, usually carries the broad `repo` scope too, so a compromised runner could reach far more than the package. `GITHUB_TOKEN` expires with the job, acts for one repository and carries only the permissions the workflow grants it.
- Naming the image after the repository links it to that repository.
- packages: write lets GITHUB_TOKEN push to any package in the organisation.
- Connecting a package after publishing always makes it inherit the repository's access.
- Adding a repository under Manage Actions access is the same as connecting the package.
- A classic token in the workflow is safer because it never expires mid-run.