Packages

One of the features that GitHub provides is a Package Repository. This allows developers to upload completed versions of their software, so that other developers can download and use them without having to build them from source (including the hassle of setting up a build environment).

At the time of writing, we're using this Package Repository to house built Java artifacts (both JAR and WAR files). This should be especially useful for developers that use common libraries (e.g. developing Agents that use the JPS Base Library).

It's recommended that developers try to install existing software using these uploaded packages rather then building them from source. However, before this can be done, a little setup is needed. There are a number of ways to download GitHub packages, an explanation using Maven is detailed below.

Getting Credentials

To download or upload GitHub packages, you'll need to generate a GitHub Personal Access Token that has an appropriate scope.

Downloading Packages with Maven

Before packages can be downloaded, Maven needs to know the location of the repository, and the credentials that should be used to access it. This is done using Maven's settings.xml and settings-security.xml files located in the ~/.m2 directory.

Note: Adding repository details to the settings.xml file is not quite the same as adding them to your project's pom.xml file. Repositories listed within the dependencyManagement element of a project, refer to the target repository (i.e. where your project's JAR/WAR files will be uploaded). Those listed in the settings.xml file are used to find and download pre-built versions of dependencies; this means that you'll still need to setup the settings.xml file even if you've added a repository to your project itself.

Maven requires that users encrypt their credentials before adding them to these files, read the Maven guide on how to do this here. An example of these files are provided within the Java Agent Example project. Simply add in your encrypted credentials.

Once these files are setup, any dependencies listed in your Java project's pom.xml file should automatically be downloaded at build time. To better understand the version number system, and determine which version of a dependency you should use, refer to the Versioning page.

A sample settings.xml file setup to access TheWorldAvatar's packages under the repo id:

<settings> 
    <!-- The path to the local repository Maven will use to store artifacts -->
    <localRepository>${user.home}/.m2/repository</localRepository>
 
    <!-- Will Maven prompt you when it needs input? If false, Maven will use a sensible default -->
    <interactiveMode>false</interactiveMode>
 
    <!-- Should Maven use the plugin-registry.xml to manage plugin version? -->
    <usePluginRegistry>false</usePluginRegistry>
 
    <!-- Should Maven operate in offline mode? -->
    <offline>false</offline>
 
    <!-- Server credentials -->
    <servers>
        <server>
            <id>repo</id>
            <username>REPO_USERNAME</username>
            <password>REPO_PASSWORD</password>
        </server>
    </servers>
    
    <profiles>
        <profile>
            <id>Default Profile</id>
            <properties></properties>
            <repositories>
                <repository>
                    <id>repo</id>
                    <url>https://maven.pkg.github.com/cambridge-cares/TheWorldAvatar/</url>
                    <layout>default</layout>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>                    
                </repository>
            </repositories>
        </profile>
    </profiles>

    <!-- List of profiles that are active for all builds. -->
    <activeProfiles>
        <activeProfile>Default Profile</activeProfile>
    </activeProfiles>	
</settings>

Uploading Packages with Maven

As developers can list many repositories in their settings.xml file (to pull dependencies from many sources), a target repository needs to be set within your Java project before an upload can take place. To do this, open your project's pom.xml file and add the following XML node (within the <project> node). Note that the id needs to match the id of the server within your settings.xml file (otherwise Maven will be unable to determine the correct credentials to use).

<distributionManagement>
    <snapshotRepository>
        <id>repo</id>
        <url>https://maven.pkg.github.com/cambridge-cares/TheWorldAvatar/</url>
    </snapshotRepository>
    <repository>
        <id>repo</id>
        <url>https://maven.pkg.github.com/cambridge-cares/TheWorldAvatar/</url>
    </repository>
</distributionManagement>

Once this is added, a Java project can be built and uploaded to the package repository using the mvn clean deploy command.

WARNING: Please ensure that your project's version number is correct before uploading, there is a risk of overwriting existing packages if the version number matches when it shouldn't.