This repository is a sample project to show you a usage of the maven github action in a dummy Java application.
We will see how you can use maven release inside a GitHub actions, to release your Java project.
Disclaimer: I am the author of the GitHub action that I will show you how to leverage today: https://github.com/qcastel/github-actions-maven-release
I will use a sample repository to illustrate how this GitHub actions. The repository can be found here: https://github.com/qcastel/github-actions-maven-release-sample
The readme of this GitHub action covers all the features it offers. Here are some highlights on some of it that you may be looking for:
- Signing the commits (GPG) resulting from the maven release
- Increment the major or minor version
- Use a bot for your release
Before you even begin setting up this github action, you would need to set up your pom.xml first to be ready for maven releases. We recommend you to refer to the maven release plugin documentation for more details: https://maven.apache.org/maven-release/maven-release-plugin/
For our sample repository, we will use the SSH remote URL to setup the scm:
<scm>
<connection>scm:git:${project.scm.url}</connection>
<developerConnection>scm:git:${project.scm.url}</developerConnection>
<url>git@github.com:qcastel/github-actions-maven-release-sample.git</url>
<tag>HEAD</tag>
</scm>
Next, you need to add the maven plugin:
<properties>
<maven-release-plugin.version>2.5.3</maven-release-plugin.version>
</properties>
<plugin>
<artifactId>maven-release-plugin</artifactId>
<version>${maven-release-plugin.version}</version>
<configuration>
<scmCommentPrefix>[ci skip]</scmCommentPrefix>
<tagNameFormat>@{project.version}</tagNameFormat>
</configuration>
</plugin>
Note: We will use the prefix [ci skip] which allows us to skip more easily any commits generated by the bot from the CI.
In our sample repository, we will assume we got a basic CI in place that build our Java application.
We will start with a basic .github/workflows/release.yaml:
name: release version
on:
push:
branches:
- master
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: Build and Test
uses: qcastel/github-actions-maven-cmd@master
with:
maven-args: "clean install"
Maven release will bump the version and by doing so, will commit into the git repository. We therefore need to setup a way of authenticating to the git repository and for this sample, we choose to use SSH.
For generating a dedicating SSH key, we will use a docker container to avoid affecting your local OS. Here is a suggested way of how you can generate a SSH public and private key:
docker run -it qcastel/maven-release:latest bash
Then run:
ssh-keygen -b 2048 -t rsa -f /tmp/sshkey -q -N ""
export SSH_PRIVATE_KEY=$(base64 /tmp/sshkey)
export SSH_PUBLIC_KEY=$(cat /tmp/sshkey.pub)
echo -n "Copy the following SSH private key and add it to your repo secrets under the name 'SSH_PRIVATE_KEY':"
echo $SSH_PRIVATE_KEY
echo "Copy the encoded SSH public key and add it as one of your repo deploy keys with write access:"
echo $SSH_PUBLIC_KEY
exit
As an output, we got:
Copy the following SSH private key and add it to your repo secrets under the name 'SSH_PRIVATE_KEY':LS0tLS1CRUdJTiBPUEVOUXXXX=
Copy the encoded SSH public key and add it as one of your repo deploy keys with write access:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC/nPud195W04be0kZkg14rH1NC/ky0PoFzFa8oqO8M4V5czs3iAMD7YXbUAE9yyMikXkMqwQinQiU27iEwBocf/IsMMBfGLgVw2cpcz+Ov1Rtl7y+QfmtVtayCDutuiJPUS9rfw/5H1DPH3+qDUTRR/ThFBc02thZYWwqq7uciPuUU+Mv5lVG/5EATDTUVCeh6Tdx7uiNKV5cFoMQPGzVQZsO/pXNr5DQlXRMd/1MJ9UgQyHTW4n3gFIGi6DlmvVnlLCEVDSEc/HAB71NB3RGk6+0kt/0/4IGqSzZ2tgtjBc/F/FPIsKYPPpWZ5IJT4wlebSZF7PYzWL4iR3Ve5Rhl root@aceee9600aee
We then go to our project repository, in the secret sections and add the key as follow:
Note: For security reason, I masked a bit the private key, the one you will copy will be much longer.
We next add the SSH public key as a deploy key with write access by going to the Deploy keyssection:
We are now ready to setup the maven release GitHub actions job. We will setup the minimal setup for starting and we will then enhance it:
- name: Release
uses: qcastel/github-actions-maven-release@master
with:
git-release-bot-name: "bot-idhub"
git-release-bot-email: "bot@idhub.io"
maven-args: "-Dmaven.javadoc.skip=true -DskipTests -DskipITs -Ddockerfile.skip -DdockerCompose.skip -Dmaven.deploy.skip=true"
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
Note: We will skip the deployment of the docker image as some of you may not have the need to containerised their Java application. We will however see how to push to docker hub in a later section.
We will also add a filter to avoid having your CI running on the commits generated by the maven release itself:
jobs:
build:
runs-on: ubuntu-latest
if: "!contains(github.event.head_commit.message, '[ci skip]')"
Once you committed this change, if everything goes well, you should see that the CI did commits for bump version change in your repository:
Congratulations! At this point you should have a functional maven release in place, which bump the version automatically.
You can stop there if that's what you were after from this maven release plugin. The other sections are optional.
You like this GitHub actions and would like to give your support and bring it up in the GitHub market place? Add a star to this repository :) Surprisingly, it seems to be the only way for the github market place to highlight popular github actions. The number of uses of it in CI is not yet publicly visible and therefore not used to highlight the most popular used GitHub actions. If you intend to use this GitHub actions, adding a star to it will help it to be more popular and therefore maintained by the GitHub community.
How to containerise a Java application is out of scope of this article. Although as I want to show you how to push to docker hub, we will quickly containerised our sample application, using Jib:
<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>jib-maven-plugin</artifactId>
<configuration>
<skip>false</skip>
<from>
<image>qcastel/docker-alpine-with-bash:0.3</image>
</from>
<to>
<image>registry.hub.docker.com/qcastel/github-actions-maven-release-sample</image>
<tags>
<tag>${project.parent.version}</tag>
<tag>latest</tag>
</tags>
</to>
</configuration>
</plugin>
Then we setup the GitHub actions to access the docker hub credentials:
with:
docker-registry-id: registry.hub.docker.com
docker-registry-username: qcastel
docker-registry-password: ${{ secrets.DOCKER_REGISTRY_PASSWORD }}
As you can see, it is setup to read a repository GitHub secrets. Here is how I setup the secret for the sample:
We then need to update our maven release job to not skip the docker build anymore. Our maven arguments now look like:
maven-args: "-Dmaven.javadoc.skip=true -DskipTests -DskipITs -Dmaven.deploy.skip=true"
Once you commit those changes, you should see that a new docker images has been pushed to docker hub!
You may be interested or have to enforce git commit signature to your repository. It's actually particular important for the CI release commits as they are the one that will ultimately produce the artefacts for your CD. We will see how you can make the CI commits done by a CI bot, with GPG signature on top.
There is currently no way in GitHub to create a bot without actually creating a GitHub account for it. Not much of a problem for public repositories but an issue for when you are paying got every users of your GitHub organisation. Unfortunately I don't have another solution to offer you, other than allocating one user of your organisation for the bot.
Very important step, don't skip it! ;)
We added earlier our SSH public key as deploy key. This is fine if you don't intend to use a bot. In our case now, we will delete that deploy key and set the public SSH key to the bot instead.
You can follow the documentation of GitHub: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key
For this sample repository, I will try to not go too much in details on how to do it but please note that in the GitHub actions readme, we got a section dedicated for GPG that may help you: https://github.com/qcastel/github-actions-maven-release#setup-the-bot-gpg-key
Go to Manage access and add the bot in there. If you got an organisation, add him at the organisation level instead.
Accept the invitation that GitHub sent to the bot email.
The CI will need to access the GPG details and it is best that they are stored as secrets:
Add the following two secrets:
GPG_KEY: Copy the GPG private key (base64 encoded!)GPG_KEY_ID: Copy the GPG key ID
You can then add to the GitHub actions the following config:
with:
gpg-enabled: true
gpg-key-id: ${{ secrets.GPG_KEY_ID }}
gpg-key: ${{ secrets.GPG_KEY }}
Once you committed those changes, you should see that the release commits are now highlighted with your bot avatar and marked as verified.
We saw how you can use maven release as part of your Github CI. From a basic setup, to push to docker hub and using a bot for your CI commits.
Your Java application may have some specificity that you need to adapt in using this github action. For example, you need Java 8 or 15, a private repository or even setup a specific branch for your release. Hopefully this should be capture in one of the options from the github action. You can find more details in the github repository of the github action itself: https://github.com/qcastel/github-actions-maven-release
As a reminder, you can find the sample project we used during this article here: https://github.com/qcastel/github-actions-maven-release-sample