GitHub Packages
Learn how to use GitHub Packages to publish and consume packages in your GitHub workflows and projects.
GitHub Packages
GitHub Packages is a package management service that allows you to host and manage packages alongside your code. It integrates seamlessly with GitHub features like Actions to provide a streamlined workflow for software development.
Understanding GitHub Packages
- Host packages privately or publicly
- Integrate with GitHub Actions for CI/CD
- Manage packages alongside your code
- Control access using existing GitHub permissions
- Share packages across your organization
- View package usage and metrics
- Support for multiple package types
GitHub Packages supports several package formats:
- npm (JavaScript)
- Maven (Java, Kotlin, etc.)
- RubyGems (Ruby)
- NuGet (.NET)
- Docker (Container images)
- Gradle (Java, Kotlin, etc.)
- Composer (PHP)
Getting Started with GitHub Packages
- Authenticate to GitHub Packages
- Configure your package manager client
- Publish your package
- Install packages from GitHub Packages
Authentication
To use GitHub Packages, you need to authenticate:
- Go to your GitHub Settings > Developer settings > Personal access tokens
- Generate a new token with the
write:packagesscope - Use this token to authenticate with your package manager
# For npm, create or edit .npmrc
//npm.pkg.github.com/:_authToken=YOUR_TOKEN
@YOUR_USERNAME:registry=https://npm.pkg.github.com
In GitHub Actions workflows, you can use the built-in GITHUB_TOKEN:
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '16'
registry-url: 'https://npm.pkg.github.com'
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Store your authentication tokens securely and never commit them to your repository. Use environment variables or secrets for tokens in CI/CD workflows.
Publishing Packages to GitHub Packages
npm Packages
-
Create or update your
.npmrcfile:@OWNER:registry=https://npm.pkg.github.com -
Update your
package.json:{ "name": "@OWNER/PACKAGE-NAME", "version": "1.0.0", "repository": { "type": "git", "url": "git://github.com/OWNER/REPOSITORY.git" } } -
Publish your package:
npm publish
Docker Images
-
Build your Docker image:
docker build -t ghcr.io/OWNER/IMAGE_NAME:TAG . -
Authenticate to the GitHub Container Registry:
echo $GITHUB_PAT | docker login ghcr.io -u USERNAME --password-stdin -
Push your image:
docker push ghcr.io/OWNER/IMAGE_NAME:TAG
Installing Packages from GitHub Packages
Update your .npmrc file:
@OWNER:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_TOKEN
Install the package:
npm install @OWNER/PACKAGE-NAME
Authenticate to the registry:
echo $GITHUB_PAT | docker login ghcr.io -u USERNAME --password-stdin
Pull the image:
docker pull ghcr.io/OWNER/IMAGE_NAME:TAG
Managing Package Access and Visibility
GitHub Packages inherits permissions from the repository it's published from:
- Public repositories: Packages are public by default
- Private repositories: Packages are private by default
- Organization repositories: Members with package access can install packages
To control package access:
- Go to your package on GitHub
- Click "Package settings"
- Under "Manage Actions access", configure your permissions
- Choose between "Private", "Public", or "Internal" visibility
Once a package is made public, it cannot be made private again. You would need to delete the package and republish it.
Integrating with GitHub Actions
Automating package publishing with GitHub Actions:
name: Publish Package
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '16'
registry-url: 'https://npm.pkg.github.com'
- run: npm ci
- run: npm test
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}