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:
- A Java project that will contain the library that you want to host via a private GitHub Packages repository
- A private GitHub repsoitory containing the code for said library
- Another Java project that will utilize said library
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
2
3on:
4 push:
5 branches: [ main ]
6
7jobs:
8 build:
9 runs-on: ubuntu-latest
10
11 permissions:
12 contents: read
13 packages: write
14
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 }}
23
24 - name: Build with Maven
25 run: mvn -B package --file pom.xml
26
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:
1permissions:
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:
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:
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):
Give your token whatever name you’d like and give it the read:packages permission:
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:
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 -->
15
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.