If you have custom-built libraries for personal or organizational projects, it’s essential to host them somewhere if you plan on making them available to the outside world or within your organization. While several repository providers exist, each has its own approval processes and validations, such as Maven Central.

If you’re already hosting your project repository on GitHub, you can take advantage of GitHub Packages. GitHub creates a http://github.com/username/<your-repo>/packages path where you can enable all your packages. Additionally, GitHub provides repository details for all major packaging solutions you can use to add your libraries as dependencies.

Objective

In this post, we’ll show you how to host existing Maven packages that are already in your possession on GitHub and make them available as dependencies. If you’re attempting to release and host packages for live projects, you can use plugins to manage that. However, we’re concentrating on local libraries that already exist in the local repository and that you want to host.

GitHub Packages

GitHub Packages is a hosting solution for packages provided by GitHub that’s particularly useful if you’ve already hosted your repositories on GitHub. The free version of GitHub Packages allows you to store up to 500MB of packages and transfer up to 1GB of data (dependency resolution) per month, which is a reasonable limit for small teams.

You can also use packages for private repositories to share them within your organization or teams. Although we’re using Maven packaging as an example, GitHub Packages supports many other packaging formats, such as Docker, npm, NuGet, and Gradle.

To learn more about GitHub Packages, please visit their website by clicking on this link: https://github.com/features/packages.

GitHub Configuration

Repo setup

GitHub packages store the packages under the path of an existing repository ( https://github.com/microideation/mi-dialogue/packages ). So it’s important to have a repository hosted in GitHub for this to work.

GitHub token with Packages access

For pushing the files to the GitHub Packages from locally, you are required to have a token with the right access.

Log in to your GitHub account -> Click the profile icon on the right -> Goto Settings -> Developer Settings ( Bottom Left Menu ) -> Personal Access Tokens -> Tokens ( Classic )

Give a name for the token and choose the below access rights

• repo
• write: packages
• delete: packages

Create the token and note down the token for future use.

Local Configuration

Maven

We are going to use the local maven installation for running commands and need to ensure that the mvn the command is available in the path ( command line ).

GitHub repo details in the maven settings file

We also need to ensure that the maven configuration file ( usually stored in ~/.m2/settings.xml ) contains the GitHub repo details for connecting to the account where we are going to host the packages.

Edit the ~/.m2/settings.xml and make sure to add the below section. Update the details to your based on your GitHub account and use the Personal token you have retrieved.

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

The full settings.xml may look something like below:

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>/Users/sandheepgr/Development/maven-repo/repository</localRepository>
	<servers>
	  <server>
	    <id>github</id>
	    <username>microideation</username>
	    <password>token</password>
	  </server>
	</servers>		
</settings>

Publishing the Package

Now that we have GitHub packages ready, we can move to the process of publishing the packages ( or libraries ). In the example below, I will publish some Maven Spring Boot dependencies ( jar file and corresponding pom ) that I want to distribute.

We are going to use the local maven installation for running commands and need to ensure that the mvn the command is available in the path ( command line ).

Let’s start with the publishing

1. Keep the files that you want to push in a specific folder ( this is should be different from the maven repo location ). If you are trying to publish a dependency that you are already using locally, you could go to the maven-repo folder and copy them from there.
2. Open the terminal and move to the location
3. Ensure that the jar file and pom file are in the location and have the necessary details. Maven will use the artifactId and groupId from the pom file for creating the package.
4. Run the below command to publish

mvn deploy:deploy-file -Dfile=./<filename>.jar -DpomFile=./<pom-filename>.pom -DrepositoryId=github -Durl=https://maven.pkg.github.com/<your-username>/<your-repo> -Dtoken=PERSONAL_ACCESS_TOKEN

Make sure to replace the yellow marked entries with your own values

• <filename>.jar -> The filename of the jar file in the folder
• <pom-filename>.jar -> The filename of the pom file
• <your-username> -> The GitHub username
• <your-repo> -> The repository name
• PERSONAL_ACCESS_TOKEN -> The Personal access token generated from GitHub

For a more detailed example, see the command that I have used for uploading the mi-dialogue-core-0.0.5.jar & mi-dialogue-core-0.0.5.pom to Packages.

mvn deploy:deploy-file -Dfile=./mi-dialogue-core-0.0.5.jar -DpomFile=./mi-dialogue-core-0.0.5.pom -DrepositoryId=github -Durl=https://maven.pkg.github.com/microideation/mi-dialogue -Dtoken=PERSONAL_ACCESS_TOKEN

Once the command is successful, it will create the package in the GitHub

Once you go into the package, you will be able to see the dependency details ( including version ) and also if there are multiple versions of the library uploaded, then can be seen on the right side.

Using the package as a dependency

You can use the package as a dependency in your maven projects very easily. Just need to have the repository configured in the pom and use the dependency as you would normally do.

Add the GitHub Packages repository to your project repositories section

<repositories>
		<repository>
			<id>github</id>
			<url>https://maven.pkg.github.com/microideation/mi-dialogue</url>
			<releases>
				<enabled>true</enabled>
			</releases>
			<snapshots>
				<enabled>true</enabled>
			</snapshots>
		</repository>
	</repositories>

Use the proper username and repo-name in the URL

After that , use the dependency as you would normally do.

<dependency>
	<groupId>com.microideation.app.dialogue</groupId>
	<artifactId>mi-dialogue-core</artifactId>
	<version>0.0.5</version>
</dependency>

Possible issues

There were a couple of issues that I encountered while uploading the packages. Listing them down here so that you can handle them in case you come across them.

401 Unauthorized from GitHub Packages

1. Check and ensure that you are using the right token with the write:packages access
2. Even though we are providing the token in the command, I was not able to upload it till the entry was added to the ~/.m2/settings.xml file ( maven settings file ) as in the configuration section specified.

Cannot upload from local maven repo

This will happen if you are trying to run the command from your local maven repo folder. You need to copy the files to a different location and run the files from there.

Footnotes

In conclusion, GitHub Packages offer a cost-effective way to host and distribute packages that you need to share with other users or within your organization team. Compared to other options like Maven Central, GitHub Packages have minimal validation processes, making it a quick and easy solution for hosting your packages.