GitHub Packages

Understanding GitHub Packages

GitHub Packages is a comprehensive software package hosting service that seamlessly integrates with your GitHub repository workflow. By combining source code management with package hosting, GitHub Packages provides a unified platform for storing, versioning, and distributing software packages across your development teams and projects. This integration eliminates the need for separate package registries and provides centralized permission management through your existing GitHub organization structure.

The platform supports multiple package ecosystems including npm for JavaScript, Maven for Java, Gradle for Java, RubyGems for Ruby, NuGet for .NET, and Docker containers. This broad ecosystem support makes GitHub Packages suitable for diverse technology stacks, allowing organizations to consolidate their package management onto a single platform while maintaining familiar tooling and workflows. The Container registry, specifically optimized for container images, supports both Docker Image Manifest V2 and Open Container Initiative specifications, enabling modern containerized application workflows.

GitHub Packages offers flexible permission models that align with your repository access controls. Packages can inherit permissions from their associated repositories, or you can configure granular permissions independently for specific users or teams. This flexibility supports various organizational structures, from tightly-controlled enterprise environments to more open-source oriented projects.

Supported Package Registries

GitHub Packages supports an extensive range of package registries:

Integrating GitHub Packages with your CI/CD pipelines enables automated package publishing and consumption as part of your continuous delivery workflow.

npm Registry Integration

The npm registry within GitHub Packages provides a powerful solution for organizations seeking to manage their JavaScript and TypeScript dependencies within their GitHub infrastructure. By publishing private npm packages to GitHub Packages, organizations maintain complete control over their intellectual property while leveraging the security and access management features of GitHub.

Authentication Setup

Setting up authentication for the npm registry requires creating a personal access token with the appropriate scopes:

• read:packages - Download packages from the registry
• write:packages - Publish new packages and versions
• delete:packages - Remove packages from the registry

Configure your .npmrc file to authenticate:

//npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN

Publishing npm Packages

Publishing npm packages to GitHub Packages requires:

1. Package name must use your GitHub scope: @namespace/package-name
2. Configure publishConfig in package.json:

{
"publishConfig": {
"registry": "https://npm.pkg.github.com"
}
}

3. Run npm publish to publish your package

The package appears in your GitHub interface with metadata, download statistics, and associated documentation.

For teams building modern web applications, maintaining a private npm registry through GitHub Packages ensures consistent dependency management across all your web development projects.

Container Registry for Docker Images

The Container registry within GitHub Packages delivers enterprise-grade container image management integrated directly into your GitHub workflow. The registry supports both Docker Image Manifest V2 and Open Container Initiative specifications, accommodating the diverse container formats used across different platforms and runtimes.

Authenticating to Container Registry

export CR_PAT=your_personal_access_token
echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin

Pushing Container Images

# Tag your image
docker tag my-image:latest ghcr.io/namespace/my-image:latest

# Push to GitHub Packages
docker push ghcr.io/namespace/my-image:latest

Pulling Container Images

# Pull by tag
docker pull ghcr.io/namespace/my-image:latest

# Pull by digest for reproducibility
docker pull ghcr.io/namespace/my-image@sha256:82jf9a84u29...

Adding Metadata with Labels

FROM node:20-alpine

LABEL org.opencontainers.image.source=https://github.com/org/repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

Containerized applications benefit from integrated CI/CD pipelines that automate build, test, and deployment workflows. Explore how to combine GitHub Actions with container registries for scalable deployment automation.

Access Control and Permissions

GitHub Packages implements a sophisticated access control system that aligns package permissions with your GitHub organization's existing structure.

Permission Models

Repository-Scoped Permissions:

• Permissions inherit from the associated repository
• Simplifies management for closely coupled source and package deployments
• Automatic workflow access to published packages

Granular Permissions:

• Configure independently from repositories
• Support for cross-repository package sharing
• Fine-grained control over who can read, write, or admin

Visibility Options

GitHub Actions Integration

GitHub Actions integration transforms package publishing from manual operations into automated pipeline steps, enabling continuous delivery of packages alongside your application deployments.

Automated Publishing Workflow

name: Publish Package
on:
 release:
 types: [created]

jobs:
 publish:
 runs-on: ubuntu-latest
 permissions:
 contents: read
 packages: write
 steps:
 - uses: actions/checkout@v4
 
 - name: Build and publish npm package
 uses: actions/setup-node@v4
 with:
 node-version: '20'
 registry-url: 'https://npm.pkg.github.com'
 
 - name: Install dependencies
 run: npm ci
 
 - name: Publish
 run: npm publish
 env:
 NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The GITHUB_TOKEN automatically receives appropriate permissions for publishing packages associated with the workflow's repository, eliminating separate credential management for CI/CD pipelines.

For complex deployment scenarios, consider using reusable GitHub Actions workflows to standardize package publishing across multiple repositories in your organization.