How to Publish Maven Artifacts to GitHub Packages

Ashraf SarhanJanuary 2nd, 2025Last Updated: December 31st, 2024

0 15 3 minutes read

GitHub Packages is a versatile platform for hosting your project’s dependencies and artifacts. It seamlessly integrates with GitHub repositories, making it a convenient solution for developers to publish Maven artifacts to GitHub Packages. In this article, we’ll cover the steps to publish a Maven artifact to GitHub Packages and demonstrate how other developers can include the package as a dependency in their Maven projects.

1. Overview

GitHub Packages integrates seamlessly with Maven, allowing developers to host and manage Java artifacts alongside their code. By leveraging GitHub Actions, you can automate the process to publish Maven artifacts to GitHub Packages, ensuring that your packages are consistently up-to-date and easily accessible.

2. Creating the Maven Project

Begin by setting up a standard Maven project structure:

project-root/
├── src/
│   ├── main/
│   │   ├── java/
│   │   └── resources/
│   └── test/
│       ├── java/
│       └── resources/
├── pom.xml

In your pom.xml, define the project coordinates and specify the repository for deployment:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-library</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <name>My Library</name>
    <description>A sample library for demonstration</description>
    <url>https://github.com/your-username/your-repository</url>

    <distributionManagement>
        <repository>
            <id>github</id>
            <name>GitHub Packages</name>
            <url>https://maven.pkg.github.com/your-username/your-repository</url>
        </repository>
    </distributionManagement>
</project>

3. Adding a License

Including a license in your project clarifies the terms under which others can use your code. To add a license:

Choose a License: Select an appropriate license for your project. GitHub offers a license selection tool to help you decide.
Add the License File: Create a LICENSE file in the root directory of your repository and insert the text of the chosen license. For example, for the MIT License:

For instance, an MIT License might look like this:

MIT License

Copyright (c) 2024 [Your Name]

Permission is hereby granted, free of charge, to any person obtaining a copy...

4. Maven Publish Artifacts to GitHub Packages

To publish your Maven artifact, you need to configure your pom.xml and authenticate with GitHub.

Update pom.xml for Distribution

Add the distribution management section:

<distributionManagement>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/your-username/your-repository</url>
    </repository>
</distributionManagement>

Authenticate with GitHub

Generate a Personal Access Token:
Go to your GitHub settings, create a token with the write:packages and read:packages scopes.
Configure Maven Settings:
Add your GitHub credentials to the ~/.m2/settings.xml file:

<servers>
    <server>
        <id>github</id>
        <username>your-username</username>
        <password>your-token</password>
    </server>
</servers>

Replace your-username with your GitHub username and your-personal-access-token with a personal access token that has the read:packages scope.

Build and Deploy the Artifact using GitHub Actions

Use the setup-java action to install the JDK and configure Maven with a settings.xml file. Authentication is handled using the GITHUB_TOKEN secret, which is automatically set for each job.

name: Publish package to GitHub Packages
on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Publish package
        run: mvn --batch-mode deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Workflow Steps

Checkout the Code:
- Uses actions/checkout to fetch the repository.
Setup Java and Maven:
- Installs the JDK.
- Configures Maven’s settings.xml to authenticate with the GitHub Packages repository using GITHUB_TOKEN.
Publish the Package:
- Executes the Maven deploy command: mvn --batch-mode deploy
- The GITHUB_TOKEN secret provides the authentication credentials.

This configuration ensures a secure and automated process for building and publishing Maven packages to GitHub Packages whenever a new release is created.

5. Installing Maven Dependencies Published to GitHub Packages

Developers who want to use your package must configure their pom.xml to include your repository and dependency.

Add the GitHub Packages Repository:
In the consuming project’s pom.xml, add the repository configuration:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/your-username/your-repository</url>
    </repository>
</repositories>

Include the Dependency
Add the dependency coordinates corresponding to your package:

<dependency>
    <groupId>com.example</groupId>
    <artifactId>my-library</artifactId>
    <version>1.0.0</version>
</dependency>

6. Conclusion

Publishing Maven artifacts to GitHub Packages is a straightforward process that involves configuring your Maven project, building your artifact, and deploying it to GitHub. This setup enables easy sharing and versioning of your Java libraries with others. With GitHub Packages, your Maven dependencies are securely hosted and readily available for public or private consumption. For more detailed information, refer to GitHub’s official documentation on publishing Java packages with Maven.