2.5 Using GitHub Packages: Managing Docker, npm, and Maven Artifacts

Level Up Your Development: Mastering GitHub Packages for Docker, npm, and Maven Artifacts

Tired of managing your Docker images, npm packages, and Maven artifacts in a scattered mess of registries? GitHub Packages is here to rescue you! It’s a built-in, integrated package hosting service that lives right within your GitHub repository. That means simplified workflows, enhanced security, and streamlined collaboration.

In this post, we’ll dive into using GitHub Packages to manage your Docker images, npm packages, and Maven artifacts. We’ll focus on practical examples and clear explanations, making it easy for both beginners and intermediate developers to get started.

Why Use GitHub Packages?

Before we jump into the how-to, let’s understand the why. GitHub Packages offers several compelling advantages:

Centralized Location: Keeps your code and your packages in one place. No more hopping between platforms!
Built-in Permissions: Leverages GitHub’s robust permission system. Control access to your packages based on repository permissions.
Versioning & Dependency Management: Easily manage different versions of your packages and track dependencies.
Tight Integration: Seamlessly integrates with GitHub Actions for automated builds and deployments.
Free for Public Packages: Open source lovers rejoice! Public packages are completely free. Private packages come with usage limits (check GitHub’s pricing).

1. Managing Docker Images with GitHub Packages

Let’s say you’ve created a custom Docker image for your application. Publishing it to GitHub Packages is surprisingly straightforward.

Prerequisites:

A GitHub account.
A GitHub repository.
Docker installed and configured on your machine.
The docker command-line tool.

Steps:

Log in to the GitHub Container Registry: Open your terminal and run the following command, replacing <YOUR_GITHUB_USERNAME> with your actual username:
```
docker login docker.pkg.github.com -u <YOUR_GITHUB_USERNAME>
```
You’ll be prompted for your GitHub password or personal access token (PAT). Important: Use a PAT with the read:packages, write:packages, and delete:packages scopes for secure authentication.
Tag Your Docker Image: Tag your existing Docker image with the correct naming convention:
```
docker tag <YOUR_IMAGE_NAME>:<YOUR_IMAGE_TAG> docker.pkg.github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>/<YOUR_IMAGE_NAME>:<YOUR_IMAGE_TAG>
```
- <YOUR_IMAGE_NAME>: The name of your Docker image.
- <YOUR_IMAGE_TAG>: A version tag (e.g., latest, 1.0.0).
- <YOUR_GITHUB_USERNAME>: Your GitHub username.
- <YOUR_REPOSITORY_NAME>: The name of your GitHub repository.
Example:
```
docker tag my-app:latest docker.pkg.github.com/myusername/my-repo/my-app:latest
```

Push the Image to GitHub Packages:

docker push docker.pkg.github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>/<YOUR_IMAGE_NAME>:<YOUR_IMAGE_TAG>

Example:

docker push docker.pkg.github.com/myusername/my-repo/my-app:latest

Verify in GitHub: Navigate to your GitHub repository. You should now see a “Packages” section where your Docker image is listed.

Pulling the Image:

To use the image elsewhere, simply pull it using Docker:

docker pull docker.pkg.github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>/<YOUR_IMAGE_NAME>:<YOUR_IMAGE_TAG>

2. Managing npm Packages with GitHub Packages

Publishing npm packages to GitHub Packages follows a similar pattern.

Prerequisites:

A GitHub account.
A GitHub repository.
Node.js and npm installed.
An npm project with a package.json file.

Steps:

Configure Your .npmrc File: Create or modify your .npmrc file (in your project directory or your home directory) with the following lines, replacing <YOUR_GITHUB_USERNAME> with your username:
```
@<YOUR_GITHUB_USERNAME>:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<YOUR_GITHUB_TOKEN>
```
- Important: Replace <YOUR_GITHUB_TOKEN> with a personal access token (PAT) that has the read:packages, write:packages, and repo scopes. Store this token securely! Never commit your token to your repository. The .npmrc file above is intentionally commented out to prevent accidentally pushing the token to your repository. Instead, you should set the NPM_TOKEN environment variable.
Set NPM_TOKEN environment variable
```
export NPM_TOKEN=<YOUR_GITHUB_TOKEN>
```
Update package.json (optional): Ensure your package.json includes the correct scope for your package. Add this line in your package.json (replace <YOUR_GITHUB_USERNAME> with your actual GitHub username):
```
"name": "@<YOUR_GITHUB_USERNAME>/<your-package-name>",
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
}
```
If you’re publishing a public package, you don’t need the scope @<YOUR_GITHUB_USERNAME>.
Publish the Package:
```
npm publish
```
This will publish your package to GitHub Packages.
Verify in GitHub: Go to your repository’s “Packages” section to confirm your package is published.

Installing the Package:

To install the package in another project, add it as a dependency:

npm install @<YOUR_GITHUB_USERNAME>/<your-package-name>

npm install <your-package-name>

depending on if it’s scoped or public.

3. Managing Maven Artifacts with GitHub Packages

Finally, let’s see how to use GitHub Packages for Maven artifacts.

Prerequisites:

A GitHub account.
A GitHub repository.
Maven installed.
A Maven project with a pom.xml file.

Steps:

Configure Your pom.xml File: Add the following <repository> and <distributionManagement> sections to your project’s pom.xml file, replacing <YOUR_GITHUB_USERNAME> and <YOUR_REPOSITORY_NAME> with your actual values:

<repositories>
    <repository>
        <id>github</id>
        <name>GitHub <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> Apache Maven Packages</name>
        <url>https://maven.pkg.github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME></url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<distributionManagement>
    <repository>
        <id>github</id>
        <name>GitHub <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> Apache Maven Packages</name>
        <url>https://maven.pkg.github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME></url>
    </repository>
    <snapshotRepository>
        <id>github</id>
        <name>GitHub <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> Apache Maven Packages</name>
        <url>https://maven.pkg.github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME></url>
    </snapshotRepository>
</distributionManagement>

Configure Your settings.xml File: In your Maven settings.xml file (usually located in ~/.m2/settings.xml), add a <server> element with your GitHub credentials. Again, use a PAT with the necessary permissions (read:packages, write:packages, repo) instead of your password.
```
<settings>
  <servers>
    <server>
      <id>github</id>
      <username><YOUR_GITHUB_USERNAME></username>
      <password><YOUR_GITHUB_TOKEN></password>
    </server>
  </servers>
</settings>
```
Deploy the Artifact: Run the following Maven command:
```
mvn deploy
```
This will deploy your artifact to GitHub Packages.
Verify in GitHub: Check your repository’s “Packages” section on GitHub.

Using the Artifact:

To use the artifact in another project, add the repository to the repositories section of the project’s pom.xml file (as shown in step 1) and add the artifact as a dependency.

Key Takeaways:

GitHub Packages offers a convenient and integrated solution for managing your Docker images, npm packages, and Maven artifacts.
Always use Personal Access Tokens (PATs) with appropriate scopes for authentication. Avoid using your password directly.
Securely store your PATs and never commit them to your repository. Use environment variables where possible.
Follow the naming conventions and configuration steps carefully for each package type.

Next Steps:

Now that you have a basic understanding of GitHub Packages, experiment with different features, explore integration with GitHub Actions for automated workflows, and dive deeper into advanced configuration options. Happy packaging!

Level Up Your Development: Mastering GitHub Packages for Docker, npm, and Maven Artifacts

Leave a Comment Cancel Reply