Adam Hacks

How To Set Up a Private Maven Repository with GitHub Packages

This quick tutorial will teach you how to use GitHub Actions to automatically build a Java library, publish it to a private GitHub Packages Maven repository, and how to use your newly hosted library in another Maven project.

Before We Begin

Let’s get a few assumptions I am making out of the way before we get started. For the purposes of this tutorial, I am assuming that you have already set up the following:

If you’ve got these steps done then you’re ready to jump in!

Step 1: The GitHub Action

As I mentioned, we are going to configure a GitHub Action that will automatically build our library and push it to GitHub Packages every time we push code changes to our main branch. To do this, we need to create an actions configuration file in the .github/workflows path. I called mine maven-publish.yml:

 1name: Create package and push to main
 4  push:
 5    branches: [ main ]
 8  build:
 9    runs-on: ubuntu-latest
11    permissions:
12      contents: read
13      packages: write
15    steps:
16      - uses: actions/checkout@v2
17      - name: Set up Java 20
18        uses: actions/setup-java@v1
19        with:
20          java-version: 20
21          server-id: github
22          settings-path: ${{ github.workspace }}
24      - name: Build with Maven
25        run: mvn -B package --file pom.xml
27      - name: Publish to GitHub Packages Apache Maven
28        run: mvn deploy -s $GITHUB_WORKSPACE/settings.xml
29        env:
30          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

I think the syntax of of this is pretty easy to follow, but there are a couple of things I will point out here.

First, this block of code:

2      contents: read
3      packages: write

When I was first figuring out how to set all of this up, I had a hard time getting it to work. It was because all of the other tutorials I could find omitted these lines. As a result, I would get a 403 Unauthorized error whenever my action would attempt to publish my jar to GitHub Packages. Anyway, these lines gives the job permissions to read the contents of the git repository and to write to the packages repository.

The other thing that’s worth mentioning is the ${{ secrets.GITHUB_TOKEN }}. This is an access token that is automatically generated by GitHub for actions to use.

If all goes well, when you push a code change to your main branch an action should be kicked off and your package should be published to GitHub Packages:

Successful GitHub Actions run

Step 2: Generate a Personal Access Token

The next thing we need to do is generate a personal access token, which will allow us to access our newly created package via Maven. To do this, go to your GitHub account settings:

GitHub Account Settings

From there, go to Developer Settings in the left-hand sidebar and choose Personal Access Tokens and choose the Tokens (Classic).

Next, Choose Generate new token and select Generate new token (classic):

GitHub Create new Classic Access Token

Give your token whatever name you’d like and give it the read:packages permission:

GitHub Classic Access Token Setup

Generate your new token. You’ll be presented with a screen that shows you the token. Make sure you copy it now because you will not be able to view it again:

GitHub Access Token Page

Step 3: Utilize the Maven Package in Your Other Project

Now that you have your access token set up you will be able to make use of your packge in another Java project. If you try at this point, however, you’re going to get a 403 unathorized error when you try to pull the package. In order to resolve this you need to edit Maven’s settings.xml.

 1 <servers>
 2    <!-- server
 3     | Specifies the authentication information to use when connecting to a particular server, identified by
 4     | a unique name within the system (referred to by the 'id' attribute below).
 5     |
 6     | NOTE: You should either specify username/password OR privateKey/passphrase, since these pairings are
 7     |       used together.
 8     |
 9    <server>
10      <id>deploymentRepo</id>
11      <username>repouser</username>
12      <password>repopwd</password>
13    </server>
14    -->
16    <!-- Another sample, using keys to authenticate.
17    <server>
18      <id>siteServer</id>
19      <privateKey>/path/to/private/key</privateKey>
20      <passphrase>optional; leave empty if not used.</passphrase>
21    </server>
22    -->
23	<server>
24		<id>github</id>
25		<username>{YOUR_USERNAME_HERE}</username>
26		<password>{YOUR_PERSONAL_ACCESS_TOKEN_HERE}</password>
27	</server>
28  </servers>

Change the above snippet to include your username and the personal access token that you just created. Save the file and you should now be able to successfully pull the package from your private GitHub Packages repository.

#Programming #GitHub #Java