Maven Package Repo

Table of Contents

• Setup
• Pulling Packages
  • Gradle
  • Docker/Docker Compose
    • Configuring Docker
    • Building with Docker
    • Building with Docker Compose
• Publishing Packages
  • Gradle
    • Configuration
    • Publishing
• Automated Releases
  • Gradle
• Appendix: Authentication Use Cases

Setup

To pull or push artifacts from/to this repository, the ~/.gradle/gradle.properties file must be created or edited with the following variables.

gradle.properties

gpr.user= (1)
gpr.key= (2)

1. Your GitHub username

2. A GitHub personal access token (see: the GitHub documentation) for an overview, or click here to generate a new personal token. You must pick at least the "read:packages" scope to download artifacts, and "write:packages" to upload.

Pulling Packages

Gradle

To consume libraries hosted in this repo, the following must be added to your build.gradle.kts file’s repositories block.

build.gradle.kts

// root repositories definition
repositories {
  // other repo defs such as mavenCentral()
  maven {
    name = "GitHubPackages"
    url  = uri("https://maven.pkg.github.com/veupathdb/maven-packages")
    credentials {
      username = project.findProperty("gpr.user") as String? ?: System.getenv("GITHUB_USERNAME")
      password = project.findProperty("gpr.key") as String? ?: System.getenv("GITHUB_TOKEN")
    }
  }
}

The fallback values GITHUB_USERNAME and GITHUB_TOKEN will be used when building the project in Jenkins.

Docker/Docker Compose

Building Docker images that depend on packages in this repo requires passing the GitHub access token to the image build. This can be done through Docker’s --build-arg argument.

Configuring Docker

To enable passing the build-time credentials to Docker, the following build args must be added to your project’s Dockerfile.

These build args will become environment variables at build time, but will not appear in the built image.

Dockerfile

FROM ...

ARG GITHUB_USERNAME
ARG GITHUB_TOKEN

...

Building with Docker

$ docker build -t 'my-image' --build-arg=GITHUB_USERNAME=my-github-username --build-arg=GITHUB_TOKEN=my-access-token .

Building with Docker Compose

$ docker-compose build --build-arg GITHUB_USERNAME=my-github-username --build-arg GITHUB_TOKEN=my-access-token

Publishing Packages

Gradle

Configuration

Apply the following changes to your build.gradle.kts file.

1. Add the maven-publish plugin to the plugins block.

   // root plugins closure
   plugins {
     // other plugins
     `maven-publish`
   }

2. Configure gradle to produce a sources jar and a javadoc jar.

   java {
     withSourcesJar()
     withJavadocJar()
   }

3. Add a publishing block.

   publishing {
   }

4. Add the publish target repository

   publishing {
     repositories {
       maven {
         name = "GitHub"
         url  = uri("https://maven.pkg.github.com/veupathdb/maven-packages")
         credentials {
           username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
           password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN")
         }
       }
     }
   }

5. Add a publication for your project.

   publishing {
     repositories {
       ...
     }
     publications {
       create<MavenPublication>("gpr") {
         from(components["java"])
       }
     }
   }

6. Optionally configure the generated pom following the instructions in the Gradle docs. An example of a customized pom can be found in the container core lib’s build file

Publishing

Once your build.gradle.kts file has been updated with the publishing configuration, publishing artifacts can be done with the following command:

./gradlew publish

Automated Releases

Gradle

Using GitHub’s workflows, the process of publishing an artifact can be handled automatically on tagging a git repo.

To set this up:

1. Add your username and publishing token to the repository’s secrets (in the repo’s settings). The username should be under the key USERNAME and the your GitHub personal access token under the key TOKEN

2. Create a new file in your repo’s root directory at the path .github/workflows/release.yml

   The contents of the release.yml file should be as follows:

   release.yml

   name: Artifact Publish
   on:
     push:
       tags:
         - '*'
   jobs:
     publish:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v2
         - name: Setup
           uses: actions/setup-java@v1
           with:
             java-version: 15
         - name: Publish Package
           run: gradle publish
           env:
             USERNAME: ${{ secrets.USERNAME }}
             TOKEN: ${{ secrets.TOKEN }}

After pushing up the new file, any tagged commit to the repository will be automatically built and deployed to GitHub Packages.

Appendix: Authentication Use Cases

How are a username/token combination transferred to Github during the following interations?

1. Manually deploy new artifacts: uses gradle.properties (or USERNAME/TOKEN env vars as backup)

2. Automatically deploy new artifacts: uses creds stored in the github repo

3. Local build into jars: uses gradle.properties (or GITHUB_* env vars as backup) with make jar

4. Local build into docker images: uses GITHUB_* env vars with make docker or extended docker build line

5. Local build with docker-compose: uses user-specified env vars with extended docker-compose build line

6. Jenkins build into docker images: use either env vars with extended docker-compose build line