Github Private Packages Maven

Posted on in github, how-to

Have been playing around with GitHub actions, where I would want to create maven jar files to be used in other projects within GitHub. The catch is that I want this to be done with private repositories so there needs to be a little bit more configuration required.

GitHub Personal Access Token (PAT)

Before getting started I needed to create a GitHub Personal Access Token (PAT), this is so that it can be used within the actions to read and write to the packages of the GitHub Repository, and later on used within the maven settings so I’m able to access the aggregated packages list of the organisation. To create a PAT go to GitHub settings and generate a new token with the following permissions:

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

Copy the generated token since you’ll need it later to authenticate Maven to GitHub Packages.

Changes to Project POM file

The next step is to ensure that the maven project of the jar to be published to GitHub Packages has had the distribution management section populated. This is so that maven knows where to publish the jar file when mvn deploy is called. Obviously replace the url with something for the package in question, USER and REPO are just place holders for this post.

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>

Maven Configuration

The next step is to configure the local maven settings.xml. You can find this file by running mvn -X which will show the location on disk. To edit this will probably need sudo rights.

1
2
3
4
5
6
7

<servers>
    <server>
        <id>github</id>
        <username>USER_NAME</username>
        <password>PERSONAL_ACCESS_TOKEN</password>
    </server>
</servers>

Firstly a server definition needs to be created, use the id of github just to be clear about where the server is, but you can change this, just be sure to change this everywhere. Next will be the username, which is your GitHub username, then the contents of the PAT created earlier in the password field.

 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>

The next step is configure a profile for maven to use, which states the locations of the servers and will use the server definition created in the previous step. Note here that the github definition doesn’t actually state the repository but uses an asterisk. This is useful as it doesn’t restrict you to only looking into a single repository package for a given organisation, however you’ll be able to access all packages organisation wide, if you have the privileges to do so.

1
2
3

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

Finally this part is not required, but rather useful to do, which states what profile is enabled by default. This enable us to run maven without having to provide a profile flag, and I’m lazy so rather not have to do it each time I either build or deploy.

Maven Deploy CLI

If no more integration is required and you only want to publish and pull manually then above is all that’s required. If you want to deploy the jar to the GitHub packages it’s as simple as follows. However each time a deployment is made, you’ll need to ensure that the version number has been updated otherwise a version conflict will occur.

1

 mvn deploy

However, this isn’t what I want, I want to be able to get GitHub to publish the package, and I want to use this jar within other projects so let’s carry on.

GitHub Action

I really don’t want to be manually deploy jar files to GitHub packages, which should really be done when the main branch is updated. So below is the workflow to achieve this.

 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 }}

This workflow uses the standard GitHub action token, as this token as read and write access to the current repository in context, and we’ve stated in the permissions section that this token is allowed to carry out this task. In the actual run section we’re stating to use the settings.xml on the runner, however we’ve stated that the server id is github which will match what we’ve put in the distribution management section of this projects pom file.

If everything has matched up correctly at the end of this action, a jar would have been published to the packages section of the repository. Before running this action the version number of the jar within the pom file needs to be updated, so there isn’t a version collision. There is a work around to this, if you’re using the releases feature of GitHub but that isn’t covered here, maybe another time.

Use JAR in Another Project

What good is publishing a jar file of reusable code, if it’s not used within other projects so let’s set this up. Firstly we need to update the pom file of the project that will be using the published jar file.

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>

The repository tags above look very similar to how the distribution management was done in the jar being published, the only difference is that the repository of the package has been replaced with an asterisk, this allows the searching of all repositories of the user/organisation that we have access to.

Next we just import the module as normal with other jar files, like we would if they were published to maven central.

1
2
3
4
5

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

Now running a mvn clean install on the current project we, should see that the jar file is downloaded from the private GitHub repository packages and everything is working.

GitHub Action for Depending Projects

There are some extra steps when using package dependencies from other repositories within an organisation which are private within GitHub actions. This is because the standard GitHub token that’s used within actions only has the writes to the current repository and no others. This is where the PAT comes in, however I would recommend creating another one, which can be saved as an organisation level secret to save repeating it everywhere, also ensuring that it expires sooner.

 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 }}

The above workflow snippet show’s what’s required for a maven project to use a jar from another repository within the organisation. This is a first working draft so it might be a little verbose and possibly improved.

↤ Harlow Bindicator Rewrite
Github Private Packages Dependabot ↦