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
Contents
Credentials Configuration
Github Actions CI
Publishing via Tag
Accessing your releases
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 |
---|---|
TITLE | BETA RELEASE |
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
This site is no longer maintained. Please visit docs.opensrp.io for current documentation.