Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Pages, Packages and Releases

GitHub Packages and Container Registry

Publish and install packages with GitHub Packages: npm, Maven and NuGet registries and the Container registry ghcr.io. Authentication, visibility, and a publish workflow.

A repository stores source code. A package stores the built, versioned thing other people install: an npm module, a Docker image, a Maven library, a NuGet package. GitHub Packages is a package hosting service attached to your account or organization, so code, issues, CI and the published artifacts all live in one place with one permission model.

What it supports

Registry Ecosystem Host
Container registry Docker and OCI images ghcr.io
npm registry JavaScript packages npm.pkg.github.com
Maven / Gradle Java libraries maven.pkg.github.com
NuGet .NET packages nuget.pkg.github.com
RubyGems Ruby gems rubygems.pkg.github.com

Python (PyPI) and Rust (crates.io) are not hosted by GitHub Packages; publish those to their normal public indexes, typically from a release workflow. Packages are free for public repositories, and private ones count against storage and data-transfer allowances for your plan.

The Container registry (ghcr.io)

The Container registry is the most popular part. Image names look like ghcr.io/OWNER/IMAGE:TAG, with the owner in lowercase. Unlike other registries, container images are not forced to be tied to one repository: you may link an image to a repository for README and permissions, or keep it independent.

Log in with a personal access token (classic) that has the write:packages scope, then push:

Terminal
echo "$GHCR_TOKEN" | docker login ghcr.io -u USERNAME --password-stdin
docker build -t ghcr.io/mona/octo-app:1.0.0 .
docker push ghcr.io/mona/octo-app:1.0.0
docker pull ghcr.io/mona/octo-app:1.0.0

Inside GitHub Actions you do not need a personal token: the built-in GITHUB_TOKEN works when the job has packages: write. A complete workflow that builds and pushes on every version tag:

YAML
name: Publish image

on:
  push:
    tags: ["v*"]

permissions:
  contents: read
  packages: write

jobs:
  image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

docker/metadata-action computes sensible tags and labels from the Git ref (a tag v1.2.3 becomes image tags 1.2.3, 1.2 and so on, depending on its settings). Docker topics such as Dockerfiles are covered in the Docker tutorial.

The npm registry

To publish an npm package to GitHub, the package name must be scoped with your owner name, for example @mona/octo-lib. In package.json set the name and optionally the registry:

JSON
{
  "name": "@mona/octo-lib",
  "version": "1.0.0",
  "publishConfig": { "registry": "https://npm.pkg.github.com" },
  "repository": "github:mona/octo-lib"
}

A workflow publishes it with the automatic token:

YAML
permissions:
  contents: read
  packages: write

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 22
      registry-url: https://npm.pkg.github.com
  - run: npm ci
  - run: npm publish
    env:
      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Consumers add a line to their .npmrc so the scope resolves to GitHub, and authenticate even for reading private packages:

INI
@mona:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Maven, Gradle and NuGet follow the same pattern: point the build tool at the registry URL, authenticate with a token that has read:packages or write:packages, and publish with the tool's usual command.

Visibility and permissions

Package access is separate from repository access:

  • Visibility is public or private (internal on enterprise plans). Public container images can be pulled by anyone without logging in; a package is private by default when first created from a private repository.
  • Permissions can be inherited from the linked repository, or set per package for users, teams and organizations (read, write, admin).
  • Retention: old versions stay until you delete them. Delete untagged or stale versions from the package page, the API, or a scheduled workflow, because they count toward storage.

Authentication for reading private packages from outside Actions needs a classic personal access token with read:packages. Fine-grained tokens do not support packages yet at the time of writing, so check the current documentation before you plan around them.

A stand-in: normalizing image names and tags

A frequent failure is a push rejected because the name has uppercase letters, or a tag contains characters Docker does not allow. The helper below, written for this lesson, builds a legal image reference. It covers common rules only (lowercase repository path, tag characters limited to letters, digits, _, ., -, at most 128 characters) and is not a full parser of the OCI specification.

JS Stand-in: image reference builder (common rules only)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good practices

  • Tag with exact versions (1.2.3) and avoid deploying a floating latest to production.
  • Link each package to its repository so users see the README and source.
  • Use the GITHUB_TOKEN in workflows; keep personal tokens for local use, short-lived and minimal.
  • Sign or attest your images (see supply-chain safety) and scan them for vulnerabilities before release.
  • Remember that public images are public: never bake secrets into image layers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which host serves GitHub's container images?

    The Container registry lives at ghcr.io.
  2. 2. What must be true of an npm package name published to GitHub Packages?

    GitHub's npm registry only accepts scoped packages matching the owner.
  3. 3. A workflow pushes an image with GITHUB_TOKEN but gets a permission error. What is the likely missing piece?

    The token needs packages: write to publish.
  4. 4. Which tag strategy is safer for production deployments?

    Exact versions are reproducible; latest changes without notice.

Summary

  • GitHub Packages hosts container images (ghcr.io), npm, Maven/Gradle, NuGet and RubyGems packages.
  • Workflows publish with GITHUB_TOKEN and packages: write; outside Actions use a token with the right package scope.
  • Package visibility and permissions are managed separately from repositories.
  • Use exact version tags, link packages to repositories, and prune old versions.

Next: Releases, Tags and Semantic Versioning