Managing GitHub Packages
1. Publishing npm Packages
| Property | Value | Description |
|---|---|---|
| name | "@org/package-name" |
Name of the npm package |
| version | "1.0.0" |
Version of the package |
| publishConfig.registry | "https://npm.pkg.github.com" |
Registry URL for publishing to GitHub Packages |
Example: Publishing to GitHub Packages
{
"name": "@myorg/my-package",
"version": "1.2.3",
"publishConfig": {
"registry": "https://npm.pkg.github.com"
}
}
Note: Ensure the
package.json includes a valid registry URL and that the user has proper permissions to publish to the GitHub organization.
Example: GitHub Actions Workflow for Publishing
name: Publish Package
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
registry-url: https://npm.pkg.github.com
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Warning: Using
GITHUB_TOKEN for publishing requires that the package is scoped to the organization or user that owns the repository.
2. Publishing Docker Images
GitHub Actions allows you to publish Docker images to the GitHub Container Registry (GHCR) as part of your CI/CD workflow.
| Step | Description | Action/Command |
|---|---|---|
| 1. Set up Docker Build | Prepare the environment for building Docker images. | uses: docker/setup-buildx-action@v3 |
| 2. Login to GHCR | Authenticate with the GitHub Container Registry. | uses: docker/login-action@v3 |
| 3. Build and Push | Build the Docker image and push it to GHCR. | uses: docker/build-push-action@v5 |
Example: Publishing Docker Image to GHCR
name: Publish Docker Image
on:
push:
branches: [ main ]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and Push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: ghcr.io/${{ github.actor }}/my-app:latest
Note: Ensure that the
GITHUB_TOKEN secret is set in your repository settings for authentication.
Warning: Make sure to set appropriate permissions for the
GITHUB_TOKEN to allow publishing packages.
3. Publishing Maven Packages
Example: Publishing to GitHub Packages
name: Publish Maven Package
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: "17"
distribution: "temurin"
- name: Publish package
run: mvn deploy
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
| Property | Description | Default |
|---|---|---|
| github.token | Token for authentication with GitHub Packages | $GITHUB_TOKEN |
| maven.settings | Path to Maven settings file | ~/.m2/settings.xml |
Note: Ensure your
pom.xml includes the correct repository configuration for GitHub Packages.Warning: The
GITHUB_TOKEN must have write:packages permissions to publish packages.Key Steps
- Create a release in GitHub
- Use
actions/checkoutto get the code - Set up Java with
actions/setup-java - Run
mvn deploywithGITHUB_TOKEN
4. Publishing NuGet Packages
| Property | Value | Description |
|---|---|---|
| name | nuget |
Name of the NuGet package to publish |
| version | 1.0.0 |
Version of the NuGet package to publish |
| id | MyPackage |
Unique identifier for the NuGet package |
| authors | John Doe |
Authors of the NuGet package |
| owners | John Doe |
Owners of the NuGet package |
| description | A sample NuGet package |
Description of the NuGet package |
| projectUrl | https://github.com/user/repo |
URL to the project repository |
| licenseUrl | https://github.com/user/repo/LICENSE |
URL to the license file |
| requireLicenseAcceptance | false |
Whether to require license acceptance |
| tags | nuget, package, dotnet |
Tags for the NuGet package |
Example: Publishing NuGet Package
name: Publish NuGet Package
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup .NET Core
uses: actions/setup-dotnet@v3
with:
dotnet-version: '6.x'
- name: Build NuGet Package
run: |
dotnet pack --configuration Release --output ./nupkg
- name: Publish to GitHub Packages
run: |
dotnet nuget push ./nupkg/*.nupkg --source https://nuget.pkg.github.com/<owner>/index.json --api-key ${{ secrets.GITHUB_TOKEN }}
Note: Ensure that the
GITHUB_TOKEN has appropriate permissions to publish packages to GitHub Packages.
Warning: The
dotnet nuget push command requires the --source parameter to point to the GitHub Packages endpoint.
5. Publishing RubyGems
| Property | Value | Description |
|---|---|---|
| name | rubygems |
Name of the package to publish |
| version | 1.0.0 |
Version of the package to publish |
| gemspec | my_gem.gemspec |
Path to the gemspec file |
| api_token | $GITHUB_TOKEN |
GitHub token for authentication |
Example: Publishing a RubyGem
name: Publish RubyGem
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 3.0
- name: Build Gem
run: gem build my_gem.gemspec
- name: Publish to GitHub Packages
run: |
gem push --key github --host https://rubygems.org my_gem-1.0.0.gem
env:
GEM_HOST_API_KEY: ${{ secrets.GITHUB_TOKEN }}
Note: Ensure the
GITHUB_TOKEN has appropriate permissions to publish packages.
6. Authenticating to GitHub Packages
| Method | Description | Requirements | Notes |
|---|---|---|---|
| Personal Access Token (PAT) | Use a GitHub PAT with read:packages scope for read access or write:packages for write access. |
A valid GitHub PAT with appropriate scopes | Recommended for CI/CD environments. Token must be stored as a secret in GitHub Actions. |
| GitHub App Token | Generate a token via a GitHub App with appropriate permissions to access packages. | GitHub App installed on the repository or organization | More secure than PATs for some use cases, but requires more setup. |
| OAuth App Token | Use an OAuth app token with read:packages or write:packages scopes. |
OAuth App registered with GitHub | Less common for CI/CD, but can be used in some workflows. |
Example: Using a Personal Access Token
name: Publish Package to GitHub Packages
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Publish to GitHub Packages
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note:
GITHUB_TOKEN is automatically provided by GitHub Actions and can be used for authenticating to GitHub Packages without needing to manually create a token.
7. Configuring Package Scope
| Option | Values | Description |
|---|---|---|
| scope | @owner |
Defines the namespace for the package, typically the GitHub username or organization name |
| package-name | my-package |
The name of the package within the scope |
| visibility | public | private |
Determines if the package is accessible to everyone or only to members of the organization |
Example: Setting Package Scope in Workflow
name: Publish Package
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
registry-url: https://npm.pkg.github.com
- name: Publish to GitHub Packages
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note: The
registry-url must be set to https://npm.pkg.github.com to publish to GitHub Packages.
Warning: Ensure that the
scope matches the owner of the repository to avoid permission issues.
8. Setting Package Visibility
| Visibility Level | Description | Access Control | Default Scope |
|---|---|---|---|
| Public | Accessible to anyone on GitHub | Read-only for all users | public |
| Private | Only visible to organization members or collaborators | Read and write access for authorized users | private |
| Internal | Visible to members of the organization only | Read and write access for authorized users | internal |
Example: Setting Package Visibility in Workflow
name: Publish Package
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Publish to GitHub Packages
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note: When publishing a package, the visibility is determined by the
access field in your package.json or the scope of the registry used. For public packages, ensure that the access property is set to public.
Warning: Setting a package to
private in GitHub Packages does not prevent it from being published to the public registry if the access field in package.json is set to public. Always verify the visibility settings before publishing.
9. Linking Packages to Repository
| Property | Description | Example |
|---|---|---|
| package.json | Defines the package metadata and dependencies | |
| registry | Points to GitHub Packages registry | https://npm.pkg.github.com |
| scope | Organization or user scope for the package | @myorg |
Example: Linking Package to GitHub Repository
npm config set @myorg:registry https://npm.pkg.github.com
npm install @myorg/my-package
Note: Ensure the
NODE_AUTH_TOKEN is set in your environment or .npmrc for authentication.
10. Versioning Packages
| Version Type | Description | Examples | Notes |
|---|---|---|---|
| Major | Breaking changes that may break existing functionality | v1.0.0 |
Increment when making incompatible API changes |
| Minor | Backward-compatible new features | v1.2.0 |
Increment when adding functionality in a backward-compatible manner |
| Patch | Backward-compatible bug fixes | v1.2.3 |
Increment when making backward-compatible bug fixes |
| Pre-release | Alpha, beta, or release candidate versions | v1.0.0-alpha.1 |
Used for testing and feedback before stable release |
| Build Metadata | Additional version information (e.g., build date, commit hash) | v1.0.0+20230405 |
Does not affect version comparison |
Example: Publishing a New Package Version
name: Publish Package
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://npm.pkg.github.com'
- name: Publish to GitHub Packages
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note: GitHub Packages supports semantic versioning (SemVer) for packages. When publishing a new package or updating an existing one, ensure that the version number follows SemVer conventions to maintain compatibility and clarity for users.
Warning: Once a version of a package is published to GitHub Packages, it cannot be overwritten or deleted. If you need to make changes to a published version, you must publish a new version with an incremented version number.
11. Managing Package Retention
| Retention Policy | Configuration | Description |
|---|---|---|
| days | 30 |
Number of days to keep packages before deletion |
| count | 10 |
Maximum number of packages to keep (oldest first) |
Example: Setting retention policy via API
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
await octokit.rest.packages.updatePackageForAuthenticatedUser({
package_type: 'npm',
package_name: 'my-package',
registry: 'github',
retention_policy: {
days: 30,
count: 10
}
});
Note: Retention policies apply to all package versions and are managed per package type.
Warning: Once a package is deleted due to retention policy, it cannot be recovered.
12. Using Package Restore
| Option | Values | Notes |
|---|---|---|
| github.token | secrets.GITHUB_TOKEN |
Default token with read/write permissions for packages |
| package-registry | github.com |
Registry URL for GitHub Packages |
| package-name | my-app |
Name of the package to restore |
Example: Restore a package in a workflow
name: Restore Package
on:
workflow_dispatch: {}
jobs:
restore:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Restore package
run: |
npm config set registry https://npm.pkg.github.com
npm install my-app
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note: Ensure the
NODE_AUTH_TOKEN is set to a valid GitHub token with package read permissions.
Warning: Package restore may fail if the token does not have appropriate permissions or if the package is private.