How to Use a Public GitHub Repository as a Maven Dependency

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, there are a few important steps required to make everything work smoothly.

In this article, we’ll walk through how to configure Maven to consume a public package from GitHub Packages, step by step.

Why GitHub Packages for Maven?

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

One important thing to note upfront:

👉 GitHub Packages requires authentication even for public Maven packages.

Prerequisites

Before you begin, make sure you have:

• 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.

Create a token with the following scope:

• 
  read:packages (required to download packages)

If you plan to publish packages as well, also include:

• write:packages

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

Step 2: Authenticate Maven with GitHub Packages

Maven reads credentials from the ~/.m2/settings.xml file.

Create or edit this file:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"

          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0

                              http://maven.apache.org/xsd/settings-1.0.0.xsd">



  <servers>

    <server>

      <id>github</id>

      <username>YOUR_GITHUB_USERNAME</username>

      <password>YOUR_PERSONAL_ACCESS_TOKEN</password>

    </server>

  </servers>



</settings>

📌 The <id> value (github) is important — Maven will use it to match credentials with repositories.

Step 3: Add the GitHub Maven Repository

Now tell Maven where to find the packages.

Option 1: Use a specific repository

Add this to your project’s pom.xml:

<repositories>

  <repository>

    <id>github</id>

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

  </repository>

</repositories>

Example:

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

⚠️ GitHub requires the repository owner name to be lowercase, even if the actual username contains uppercase letters.

Option 2: Use all repositories under an owner

If you consume multiple packages from the same GitHub user or organization:

<repositories>

  <repository>

    <id>github</id>

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

  </repository>

</repositories>

This approach is often more flexible.

Step 4: Add the Dependency

Once the repository is configured, add the dependency like any other Maven artifact:

<dependencies>

  <dependency>

    <groupId>com.example</groupId>

    <artifactId>my-library</artifactId>

    <version>1.0.0</version>

  </dependency>

</dependencies>

Make sure:

• The package version exists in GitHub Packages


• The artifactId is lowercase (GitHub enforces this)

Step 5: Build the Project

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 Pitfalls

Here are a few common issues developers run into:

• ❌ Assuming public packages don’t need authentication


• ❌ Mismatched <id> values between settings.xml and pom.xml
  


• ❌ Using uppercase letters in artifactId
  


• ❌ Incorrect GitHub Packages URL

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

Final Thoughts

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 🚀