Skip to main content

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/checkout to get the code
  • Set up Java with actions/setup-java
  • Run mvn deploy with GITHUB_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
{
  "name": "@myorg/my-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}
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.

Was this article helpful?