How to Use a Public GitHub Repository as a Maven Dependency

Source: Dev.to

Introduction

Apache Maven is the backbone of most Java projects, and GitHub Packages provides a convenient way to host and distribute Maven artifacts. Even when your repository is public, a few important steps are required to make everything work smoothly.

GitHub Packages allows you to:

• Host Maven artifacts alongside your source code
• Control access to packages
• Keep dependencies close to your repositories
• Integrate seamlessly with GitHub Actions

Note: GitHub Packages requires authentication even for public Maven packages.

Prerequisites

• A GitHub account
• A public repository that publishes Maven packages
• Maven installed locally
• Basic familiarity with pom.xml

Step 1 – Create a GitHub Personal Access Token (PAT)

GitHub Packages only supports classic personal access tokens.

Keep this token safe — you’ll use it as your Maven password.

Configure Maven Credentials (settings.xml)

Maven reads credentials from ~/.m2/settings.xml. Create or edit the file with the following content:

<servers>
  <server>
    <id>github</id>
    <username>YOUR_GITHUB_USERNAME</username>
    <password>YOUR_PERSONAL_ACCESS_TOKEN</password>
  </server>
</servers>

• The <id> value (github) is important; Maven will match this ID with the repository definition in pom.xml.

Add the GitHub Packages Repository to pom.xml

<repositories>
  <repository>
    <id>github</id>
    <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url>
  </repository>
</repositories>

Example

<url>https://maven.pkg.github.com/mewan/my-public-repo</url>

Important: The repository owner name must be lowercase, even if the actual username contains uppercase letters.

If you need to consume multiple packages from the same GitHub user or organization, you can use a wildcard:

<url>https://maven.pkg.github.com/OWNER/*</url>

Declare the Dependency

Add the dependency to your pom.xml as you would for any Maven artifact:

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

Make sure:

• The package version exists in GitHub Packages.
• The artifactId is lowercase (GitHub enforces this).

Run Maven as usual:

mvn clean install

If authentication and configuration are correct, Maven will download the package from GitHub Packages and include it in your build.

Common Issues

Double‑checking these details can save a lot of time.

Conclusion

Using GitHub Packages as a Maven registry is a powerful way to manage dependencies, especially when your code already lives on GitHub. While the authentication requirement for public packages may feel surprising, once configured the workflow is smooth and reliable. If you’re already using GitHub Actions, this setup integrates nicely into CI/CD pipelines as well.

Happy coding! 🚀