How to set up Server Library artifact CI/CD on Github

Intro

This article documents the the automation of the OpenSRP server libraries releases through the integration of the process to CI on Github.

This set up also supports tagging releases on Github as pre-releases if they include alpha or beta keyword in the tag e.g. v2.3.5-alpha

For steps to manually publish the artefacts see How to upload Server libraries to Maven/Sonatype

Credentials configuration

Github

Your applications build configuration should have the Nexus credentials configured in-order to be authorised to upload an artifact in the OpenSRP organization/group on sonatype.

The values of the credentials are configured as Environment Variables which will be saved on Github as repository secrets and injected in CI when the Github Action step for building the release is running.

The environment variable names should match the key for secret stored on the Github Repository Secrets

NOTE: You need admin rights on the repo to access the repo’s Settings menu and set up the credentials

Application level

At the application love we need to access credentials as described in the manual approach documented here. That is, we need to store credentials on file in the path ${user.home}/.m2/settings.xml

We will need to generate and store the base64 encoded versions of the content of this file. This content will then be stored as a Github secret on our repo for retrieval later by our Github Action workflow.

In our case, we store the base64 content of the file above under the variable name SETTINGS_XML. This will be retrieved later from the workflow as ${{ secrets.SETTINGS_XML }}

You can convert your settings.xml file to Base64 using the following command that uses the openssl utility openssl base64 < settings.xml | tr -d '\n' | tee settings_xml_base64_encoded.txt

NB: You need admin rights on the repo to access Settings menu

Github Actions CI

You can create a new Github action workflow file and name it release.yml with the following sample configuration used for building, tagging and publishing OpenSRP Server Core as a Github release and a Sonatype artefact

NOTE: Remember to update the content with the module names corresponding to your project.

# This workflow will build a Java project with Gradle
# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-gradle

name: Snapshot Release

on:
  push:
    tags:
      - v[0-9]+.[0-9]+.[0-9]+-SNAPSHOT
      - v[0-9]+.[0-9]+.[0-9]+-[0-9a-zA-Z]+-SNAPSHOT
      - v[0-9]+.[0-9]+.[0-9]+-[0-9a-zA-Z]+-[0-9a-zA-Z]+-SNAPSHOT 

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Cancel previous workflow runs
        uses: styfle/cancel-workflow-action@0.9.1
        with:
          access_token: ${{ github.token }} 

      - uses: actions/checkout@v2
        with:
         submodules: recursive

      - name: Set up JDK 11
        uses: actions/setup-java@v1
        with:
          java-version: 11

      - name: Decode & Generate Settings.xml file
        run: echo $SETTINGS_FILE | base64 -di > ~/.m2/settings.xml
        env:
          SETTINGS_FILE: ${{ secrets.SETTINGS_XML }}

      - name: Generate & upload library snapshot artifact JAR (Java Archive) file
        run: mvn clean deploy -Dmaven.test.skip=true --no-transfer-progress 

      - name: Github Release
        uses: softprops/action-gh-release@v1
        with:
          prerelease: ${{ contains(github.ref, '-alpha') || contains(github.ref, '-beta') }}

Publishing via TAG

As part of integrating Continuous Delivery(CD) into the development lifecycle, CI has been set up to trigger artefact generation. The configuration requires the tag to have a prefix in the glob pattern formats:

v[0-9]+.[0-9]+.[0-9]+-SNAPSHOT

v[0-9]+.[0-9]+.[0-9]+-[0-9a-zA-Z]+-SNAPSHOT

v[0-9]+.[0-9]+.[0-9]+-[0-9a-zA-Z]+-[0-9a-zA-Z]+-SNAPSHOT

Thus the following are all valid tags that will trigger the generation of a release APK

v2.0.3-SNAPSHOT
v2.0.3-ALPHA-SNAPSHOT
v2.0.3-PREVIEW-SNAPSHOT
v2.0.3-rc1-PREVIEW-SNAPSHOT

Note: e.g. when creating a tag for the server core version 2.0.3, use the command:

git tag -a v2.0.3-SNAPSHOT -s && git push origin v2.0.3-SNAPSHOT

When you run the command, you will be prompted to add a message. The message should be of the format:

Template	Sample

Template	Sample
TITLE - Release note 1 - Release note 2	BETA RELEASE - Adds 2 Factor authentication - Fixes middle name missing from user endpoint

NOTE: For convention, the TITLE should be Capitalized. The release notes should show to what was updated.

Also please see Semantic versioning

Accessing your releases

Once the above command is executed and the tag is pushed, Github CI triggers an action to build the artefact and upload it to Sonatype.

One can access the published artefacts under the OpenSRP group on Sonatype below:
See OpenSRP organization/group on Sonatype

Documentation