Making Private Maven Packages Work on GitHub

I’ve been messing around with GitHub Actions lately, trying to streamline how to publish and share Java libraries across projects. The tricky part? All repos are private, which makes things way more complicated than they need to be. If you’re in the same boat, here’s how I got everything working.

GitHub Personal Access Token (PAT)

First thing you’ll need is a GitHub Personal Access Token. I spent way too long trying to make this work with just the default repo tokens before realizing you really do need a PAT with specific permissions.

Head over to your GitHub settings and create a new token with these permissions:

• repo (needed for private repositories)
• write:packages
• read:packages

Make sure you copy that token somewhere safe right after creating it! GitHub only shows it once, and I’ve had to regenerate these things more times than I care to admit.

Changes to Project POM file

Next up, you need to tell your project where to publish the jar file. Add this to your pom.xml file:

1
2
3
4
5
6
7

<distributionManagement>
    <repository>
      <id>github</id>
      <name>GitHub Packages</name>
      <url>https://maven.pkg.github.com/USER/REPO</url>
    </repository>
</distributionManagement>

Obviously replace USER/REPO with your actual GitHub username and repository. I always forget to do this and spend 20 minutes wondering why things aren’t working.

Maven Configuration

Now we need to configure Maven itself. Run mvn -X to find where your settings.xml file lives (you’ll probably need sudo rights to edit it).

Add this server definition:

1
2
3
4
5
6
7

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

The ID must match what you used in the distributionManagement section (I just use “github” everywhere to keep things simple).

Next, set up a profile:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

<profile>
    <id>github</id>
        <repositories>
            <repository>
                <id>github</id>
                <url>https://maven.pkg.github.com/USER/*</url>
                <snapshots>
                    <enabled>true</enabled>
                </snapshots>
            </repository>
            <repository>
                <id>central</id>
                <url>https://repo1.maven.org/maven2</url>
            </repository>
        </repositories>
    </profile>
</profiles>

See that wildcard asterisk in the URL? That’s the secret sauce! It lets Maven search through all your organization’s repositories for packages instead of just one specific repo. I wasted hours trying to figure this out.

Finally, make this profile active by default (because who wants to type -P github every time?):

1
2
3

<activeProfiles>
    <activeProfile>github</activeProfile>
</activeProfiles>

Maven Deploy CLI

If you want to test things out manually, just run:

1

mvn deploy

Just remember to bump your version number each time, or you’ll get really cryptic version conflict errors. Ask me how I know…

GitHub Action

Let’s be honest though - nobody wants to manually deploy packages. Here’s the workflow I set up to do it automatically whenever code hits the main branch:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

name: Build and Deploy Package

on:
  push:
    branches:
      - main
jobs:
  build:

    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
    - uses: actions/checkout@v4
    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        server-id: github 
        cache: 'maven'
        settings-path: ${{ github.workspace }} 

    - name: Publish to GitHub Packages Apache Maven
      run: |
        mvn deploy -s settings.xml        
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The cool thing here is that you don’t need your PAT for this part - the default GITHUB_TOKEN has enough permissions to publish packages to the current repo.

Use JAR in Another Project

Now for the fun part - actually using your library in another project. Add this to your consumer project’s pom.xml:

1
2
3
4
5
6
7

<repositories>
    <repository>
        <id>github</id>
        <name>GitHub OWNER Apache Maven Packages</name>
        <url>https://maven.pkg.github.com/USER/*</url>
    </repository>
</repositories>

Again, the wildcard is your friend. Then just add your dependency like any other jar:

1
2
3
4
5

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

Run mvn clean install and if everything’s set up correctly, Maven should pull your private package without complaining.

GitHub Action for Depending Projects

Here’s the tricky part - if you want a GitHub Action to build a project that depends on your private package, the default token won’t work anymore. You need to use a PAT again.

Here’s what worked for me:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

env:
  REGISTRY: ghcr.io

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: read

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: 'maven'
        server-id: github 
        server-username: GITHUB_USER_REF  
        server-password: GITHUB_TOKEN_REF 

    - name: Build and Test with Maven
      run: |
        mvn -B -Pgithub install --file pom.xml        
      env:
        GITHUB_USER_REF: ${{ secrets.MVN_USER }}
        GITHUB_TOKEN_REF: ${{ secrets.MVN_KEY }}

This time you do need to use your own secrets (I recommend creating organization-level secrets rather than adding them to each repo).

I’m sure there’s a cleaner way to do all of this, but hey - it works! And after the hours I spent figuring it out, that’s good enough for me.