Repository: qcastel/github-actions-maven-release Branch: master Commit: 70725f21eb10 Files: 6 Total size: 24.1 KB Directory structure: gitextract_rfmmfgnl/ ├── .github/ │ ├── FUNDING.yml │ └── workflows/ │ └── release.yml ├── Dockerfile ├── README.md ├── action.yml └── release-github-actions.sh ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/FUNDING.yml ================================================ # These are supported funding model platforms github: [qcastel] ================================================ FILE: .github/workflows/release.yml ================================================ on: push: branches: - master name: Create Release jobs: build: name: Create Release runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v2 - name: Bump version and push tag id: tag_version uses: mathieudutour/github-tag-action@v5 with: github_token: ${{ secrets.GITHUB_TOKEN }} - name: Create a GitHub release uses: ncipollo/release-action@v1.9.0 with: tag: ${{ steps.tag_version.outputs.new_tag }} name: Release ${{ steps.tag_version.outputs.new_tag }} body: ${{ steps.tag_version.outputs.changelog }} ================================================ FILE: Dockerfile ================================================ FROM qcastel/maven-release:0.0.44 COPY ./release-github-actions.sh /usr/local/bin ================================================ FILE: README.md ================================================ # github action maven release The GitHub Action for Maven releases wraps the Maven CLI to enable Maven release. For example, you can use this action for auto-incrementing your project version and release your java artifacts. This github action is bot friendly: You can configure the credentials of a bot user, which would be used during the incremental commit. The commits by the bot can also be signed, giving you the guaranty that only the bot can release in your repo. Additionally, this give you a clean git history by highlighting nicely which commits where resulting from your CI. ## Supporting this github action Support this github action by staring this project. Surprisingly, it seems to be the only way for the github market place to highlight popular github actions. ## Sample repository We created a sample repository that will show you an example of how this github action can be used for releasing a Java application: https://github.com/qcastel/github-actions-maven-release-sample ## Features Obviously, this github actions uses maven release plugin. Although, we did add on top a few features that you may like. Maven release uses Git behind it, therefore there were a few features related in customising the git configuration: - Signing the commits (GPG) resulting from the maven release [[GPG](#setup-a-gpg-key)] - Authenticating to private repository using an SSH key [[SSH](#setup-with-ssh)] - Configuring the git username and email [[Bot](#customise-the-bot-name)] - Configuring the jdk version [[JDK](#jdk-version)] You may want to configure a bit maven too. We added the following features: - Specify the maven project path. In other words, if your maven project is not at the root of your repo, you can configure a sub path. [[Custom project path](#customise-the-m2-folder-path)] - Configure private maven server repositories [[Private maven repo](#Setup-private-maven-server-repositories)] - Configure a docker registry [[Docker registry](#setup-a-docker-registry)] - Setup custom maven arguments and/or options to be used when calling maven commands [[Maven options](#maven-options)] - Configure a custom M2 folder [[Custom M2](#customise-the-m2-folder-path)] - Print the timestamp for every maven logs. Handy for troubleshooting performance issues in your CI. [[Log timestamp](#log-timestamp)] For the maven releases, we got also some dedicated functionalities: - Skip the maven perform [[Skip perform](#skipping-perform)] - Roll back the maven perform if it failed to perform the release - Increment the major or minor version (by default, it's the patch version that is increased) [[Major Minor version](#increase-major-or-minor-version)] - customise the version format completly [[Customize version](#customize-version)] # Usage ## Setup your pom.xml for maven 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/ Nevertheless, we will give you some essential setups ### Configure the SCM You got two choices here: - Using SSH URL (Recommended) ```xml scm:git:${project.scm.url} scm:git:${project.scm.url} git@github.com:idhub-io/idhub-api.git HEAD ``` - Using HTTPS URL ```xml scm:git:${project.scm.url} scm:git:${project.scm.url} https://github.com/YOUR_REPO.git HEAD ``` In the case of SSH, it will use the `ssh-private-key` to authenticate with the upstream. In the case of HTTPS, maven releases will use the `access-token` in this github actions to authenticate with the upstream. Note: SSH is more elegant and usually the easiest one to setup due to the large amount of documents online on this subject. ### maven release plugin Add the maven release plugin dependency to your project ```xml maven-release-plugin XXX [ci skip] ``` Personally, I usually the prefix `[ci skip]` which allows me to skip more easily any commits generated by the bot from the CI. ## Setup the maven release github actions ### Choose your version of this github action If it's your first time using a github action, I invite you having a quick read to the github official recommendations: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions It's important you understand how the versioning work and the risk/compromise of using master/tags/commit hash If you are adventurous and like to be always on top of this github action, you can use the reference *master* : ``` - name: Release uses: qcastel/github-actions-maven-release@master with: ``` If you are more reserve, you can use a tag instead. You can find the list of the tags for this github action here: https://github.com/qcastel/github-actions-maven-release/tags To use a tag: ``` - name: Release uses: qcastel/github-actions-maven-release@TAG_NAME with: ``` If you are concerned about the security of this github action, you can also move to a commit hash: ``` - name: Release uses: qcastel/github-actions-maven-release@COMMIT_HASH with: ``` ### Basic setup For a simple repo with not much protection and private dependency, you can do: ```yaml env: JAVA_HOME: /usr/lib/jvm/java-17-openjdk/ with: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} ``` You will need to follow the `Setup with SSH` section to setup the `SSH_PRIVATE_KEY` accordingly. ### Setup with SSH Although you may found better to use a SSH key instead. For this, generate an SSH key with the method of your choice, or use an existing one. Personally, I like generating an SSH inside a temporary docker image and configure it as a deploy key in my repository: ```bash docker run -it qcastel/maven-release:latest bash ``` ```bash 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 ``` Copy `SSH_PRIVATE_KEY` and add it as a new secret. ![img/Add-ssh-secrets.png](img/Add-ssh-secrets.png?raw=true) Copy `SSH_PUBLIC_KEY` and add it as a new deployment key with write access. ![img/add-deploy-key.png](img/add-deploy-key.png?raw=true) Finally, setup the github action with: ```yaml with: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} ``` If you want to set up a passphrase for your key: ```yaml with: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} ssh-passphrase: ${{ secrets.SSH_PASSPHRASE }} ``` #### SSH known hosts The current github actions support by default the following known hosts: - `github.com` - `gitlab.com` - `bitbucket.org` Although you may want to additional one, using the following properties: ```yaml with: ssh-extra-known-host: "my-awesome-private-git-host.com" ``` You can also disable the default hosts (for example, if you are behind a corporate proxy) like so: ```yaml with: ssh-ignore-default-hosts: true ``` ### log Timestamp It can be quite difficult to troubleshoot any performance issue on your CI, due to the lack of timestamp from maven by default. An example of it particular handy, is when you private maven repository is having performance issue that is affecting your CI. We added the timestamp by default, you don't need to do anything particular to enable this feature. The logs should look like: ``` 14:27:09,491 [INFO] Downloading from spring-snapshots: https://repo.spring.io/snapshot/io/projectreactor/reactor-bom/Dysprosium-SR13/reactor-bom-Dysprosium-SR13.pom ``` ### Maven options #### Adding maven arguments You can add some maven arguments, which is handy for skipping tests: ```yaml with: maven-args: "-Dmaven.javadoc.skip=true -DskipTests -DskipITs -Ddockerfile.skip -DdockerCompose.skip" ``` #### Adding maven options You can add some maven options. At the difference of the maven arguments, those one are explicitly for the maven release plugin. See https://maven.apache.org/maven-release/maven-release-plugin/prepare-mojo.html. ```yaml with: maven-options: "-DbranchName=hotfix" ``` ### JDK version The default JDK version is JDK 21. Although you may want to compile your project with a specific JDK version. You will need to specify the JAVA_HOME variable with the according value. If you need a specific jdk version that is not in the list, please raise an issue in this github action to request it. #### JDK 8 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-1.8-openjdk/ ``` #### JDK 11 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-11-openjdk/ ``` #### JDK 14 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-14-openjdk/ ``` #### JDK 15 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-15-openjdk/ ``` #### JDK 16 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-16-openjdk/ ``` #### JDK 17 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-17-openjdk/ ``` #### JDK 21 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-21-openjdk/ ``` #### JDK 25 ```yaml env: JAVA_HOME: /usr/lib/jvm/java-25-openjdk/ ``` ### Customise the bot name You can simply customise the bot name as follows: ```yaml with: git-release-bot-name: "release-bot" git-release-bot-email: "release-bot@example.com" ``` ### Customise the default branch You may not want to release from your master branch, which is currently the default branch setup by this github action. You can customise the branch name you want to release on, here `release`, as follows: ```yaml with: release-branch-name: "release" ``` ### Skipping perform If for a reason, you need to skip the maven release perfom, you can disable it as follow: ```yaml with: skip-perform: true ``` ### Increase major, minor or patch version #### For major version increment _1.0.0-SNAPSHOT -> 2.0.0-SNAPSHOT_ ```yaml with: version-major: true ``` #### For minor version increment _1.0.0-SNAPSHOT -> 1.2.0-SNAPSHOT_ ```yaml with: version-minor: true ``` #### For patch version increment As the patch version is the default version number increased, you don't need to specify any additional properties. Although if you prefer to be explicit, you can use the following option: _1.0.0-SNAPSHOT -> 1.0.1-SNAPSHOT_ ```yaml with: version-patch: true ``` ### Customize version #### development version You may want to fully customize the development version number. This option will allow you to fully take control on the version number format. For Example, you could decide to only have a 2 part version number like `0.2-SNAPSHOT`. ```yaml with: maven-development-version-number: ${parsedVersion.majorVersion}.\${parsedVersion.nextMinorVersion}-SNAPSHOT ``` ### Release version You may want to fully customize the release version number. This option will allow you to fully take control on the version number format. For Example, you could decide to only have a trailing 0 for releases like `0.2.0`. ```yaml with: maven-release-version-number: ${parsedVersion.majorVersion}.\${parsedVersion.minorVersion}.0 ``` #### Customise the M2 folder path It's quite common for setting up a caching of your dependencies, that you will be interested to customise the .m2 localisation folder. ```yaml with: m2-home-folder: '/your-custom-path/.m2' ``` ### Setup a GPG key If you want to set up a GPG key, you can do it by injecting your key via the secrets: Note: `GITHUB_GPG_KEY` needs to be base64 encoded. if you haven't setup a GPG key yet, see next section. ```yaml with: gpg-enabled: "true" gpg-key-id: ${{ secrets.GITHUB_GPG_KEY_ID }} gpg-key: ${{ secrets.GITHUB_GPG_KEY }} ``` In case you want to skip the GPG step, you can set `gpg-enabled: "false"` or if you prefer to have the same behaviour in your IDE, add this maven plugin in your `pom.xml` to skip GPG step in the release phase: ```xml org.apache.maven.plugins maven-gpg-plugin 1.6 true ``` ### Setup private maven server repositories If you got a private maven repo to set up in the settings.xml, you can do: Note: we recommend putting those values in your repo secrets. ```yaml with: maven-servers: ${{ secrets.MVN_REPO_SERVERS }} ``` Github actions currently don't support arrays input format. This is why we choose to request the secret `MVN_REPO_SERVERS` to be a JSON containing the servers definition. Example: ```json [ { "id": "serverId1", "username": "username", "password": "password1", "privateKey": "privatekey1", "passphrase": "passphrase1" }, { "id": "serverId2", "username": "username2", "password": "password2" } ] ``` You will need to put the JSON in one line: ```bash MVN_REPO_SERVERS='[{"id": "serverId1", "username": "username", "password": "password1", "privateKey": "privatekey1", "passphrase": "passphrase1"}, {"id": "serverId2", "username": "username2", "password": "password2"}]' ``` ### Setup a docker registry If you got a private maven repo to set up in the settings.xml, you can do: Note: we recommend putting those values in your repo secrets. ```yaml with: docker-registry-id: your-docker-registry-id docker-registry-username: ${{ secrets.DOCKER_REGISTRY_USERNAME }} docker-registry-password: ${{ secrets.DOCKER_REGISTRY_PASSWORD }} ``` Note: For docker hub, this would look like: ```yaml with: docker-registry-id: registry.hub.docker.com docker-registry-username: ${{ secrets.DOCKER_HUB_USERNAME }} docker-registry-password: ${{ secrets.DOCKER_HUB_PASSWORD }} ``` ### Configure your maven project You may also be in the case where you got more than one maven projects inside the repo. We added an option that will make the release job move to the according directly before running the release: ```yaml with: maven-project-folder: "sub-folder/" ``` ## Setup the bot gpg key Setting up a gpg key for your bot is a good security feature. This way, you can enforce sign commits in your repo, even for your release bot. ![Screenshot-2019-11-28-at-20-47-06.png](https://i.postimg.cc/9F6cxpqm/Screenshot-2019-11-28-at-20-47-06.png) - Create dedicate github account for your bot and add him into your team for your git repo. - Create a new GPG key: https://help.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key This github action needs the key ID and the key base64 encoded. ```yaml with: gpg-enabled: true gpg-key-id: ${{ secrets.GPG_KEY_ID }} gpg-key: ${{ secrets.GPG_KEY }} ``` If you want to set up a passphrase: ```yaml with: gpg-enabled: true gpg-key-id: ${{ secrets.GPG_KEY_ID }} gpg-key: ${{ secrets.GPG_KEY }} gpg-passphrase: ${{ secrets.GPG_PASSPHRASE }} ``` ### Generate the key f you like how we created a SSH key pair, here is the same idea using a docker image to generate a GPG key: ```bash docker run -it qcastel/maven-release:latest bash ``` ```bash cat >genkey-batch < ssb rsa2048/7D1523C9952204C1 2019-11-28 [E] ``` The key ID for my bot is 3EFC3104C0088B08. Add this value into your github secret for this repo, under `GPG_KEY_ID` PS: the key id is not really a secret but we found more elegant to store it there than in plain text in the github action yml ### Get the GPG public and private key Now we need the raw key and base64 encode ```bash echo 'Public key to add in your bot github account:' gpg --armor --export FFD651809B1889DF echo 'Private key to add to the CI secrets under GITHUB_GPG_KEY:' gpg --export-secret-keys --armor FFD651809B1889DF | base64 exit ``` Copy the public key and import it to the bot account as a GPG key. Copy the private key and add it in your github repo secrets under `GPG_KEY`. # License The Dockerfile and associated scripts and documentation in this project are release under the MIT License. ================================================ FILE: action.yml ================================================ # action.yml name: 'Java Maven release' author: https://github.com/qcastel description: 'Release your Java application and publish artifacts' branding: color: gray-dark icon: aperture inputs: release-branch-name: description: 'Filter the branch to execute the release on' required: false default: 'master' gpg-enabled: description: 'Enable gpg signing' required: false default: false gpg-key-id: description: 'The GPG key ID' required: false gpg-key: description: 'The GPG key' required: false gpg-passphrase: description: 'The GPG passphrase' required: false ssh-private-key: description: 'The SSH private key used during the maven release git commit' required: false ssh-passphrase: description: 'The SSH passphrase' required: false ssh-extra-known-host: description: 'Additional SSH known host' required: false ssh-ignore-default-hosts: description: 'Do not add the default SSH known hosts' required: false git-release-bot-name: description: 'The git user name for committing the release' required: false default: 'release-bot' git-release-bot-email: description: 'The git user email for committing the release' required: false default: 'release-bot@github.com' git-skip-sanity-check: description: 'Skip the git fetch and reset executed for safety by this action' required: false default: 'false' maven-repo-server-id: description: '!!DEPRECATED: Use maven-servers instead!! Maven server repository id to push the artifacts to' required: false default: '' maven-repo-server-username: description: '!!DEPRECATED: Use maven-servers instead!! Maven server repository username' required: false default: '' maven-repo-server-password: description: '!!DEPRECATED: Use maven-servers instead!! Maven server repository password' required: false default: '' maven-servers: description: 'The maven server repositories, in a JSON format. Example: [{"id": "serverId1", "username": "username", "password": "password1", "privateKey": "privatekey1", "passphrase": "passphrase1"}, {"id": "serverId2", "username": "username2", "password": "password2"}]' required: false default: '[]' maven-args: description: 'The maven arguments for the release' required: false default: '' maven-project-folder: description: 'You may have more than one maven projects inside the repo. This option allows you to specify the folder for which you want to trigger the release' required: false default: './' maven-options: description: 'The maven options for the release' required: false default: '' maven-development-version-number: description: 'If define, this option allows you to define a custom development version number, like ${parsedVersion.majorVersion}.${parsedVersion.nextMinorVersion}-SNAPSHOT' required: false default: '' maven-release-version-number: description: 'If define, this option allows you to define a custom release version number, like ${parsedVersion.majorVersion}.${parsedVersion.minorVersion}.0' required: false default: '' docker-registry-id: description: 'The ID of your registry. For example, for docker hub, it is `registry.hub.docker.com`' required: true default: 'fake' docker-registry-username: description: 'The username for your docker registry' required: true default: 'fake' docker-registry-password: description: 'The password for your docker registry' required: true default: 'fake' skip-perform: description: 'Skip maven release perform' required: false default: false version-major: description: 'Increment the major version number' required: false default: false version-minor: description: 'Increment the minor version number' required: false default: false version-patch: description: 'Increment the patch version number <- By default, we will increase the patch version' required: false default: false m2-home-folder: description: 'M2 home folder' required: false default: '/root/.m2' access-token: description: 'Github access token. https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line' required: false runs: using: 'docker' image: 'Dockerfile' args: - release-github-actions.sh env: GPG_ENABLED: ${{ inputs.gpg-enabled }} GPG_KEY_ID: ${{ inputs.gpg-key-id }} GPG_KEY: ${{ inputs.gpg-key }} GPG_PASSPHRASE: ${{ inputs.gpg-passphrase }} SSH_PRIVATE_KEY: ${{ inputs.ssh-private-key }} SSH_ROOT_FOLDER: /root/.ssh SSH_PASSPHRASE: ${{ inputs.ssh-passphrase }} SSH_EXTRA_KNOWN_HOST: ${{ inputs.ssh-extra-known-host }} SSH_IGNORE_DEFAULT_HOSTS: ${{ inputs.ssh-ignore-default-hosts }} MAVEN_REPO_SERVER_ID: ${{ inputs.maven-repo-server-id }} MAVEN_REPO_SERVER_USERNAME: ${{ inputs.maven-repo-server-username }} MAVEN_REPO_SERVER_PASSWORD: ${{ inputs.maven-repo-server-password }} MAVEN_SERVERS: ${{ inputs.maven-servers }} MAVEN_PROJECT_FOLDER: ${{ inputs.maven-project-folder }} MAVEN_ARGS: ${{ inputs.maven-args }} MAVEN_OPTION: ${{ inputs.maven-options}} MAVEN_DEVELOPMENT_VERSION_NUMBER: ${{ inputs.maven-development-version-number}} MAVEN_RELEASE_VERSION_NUMBER: ${{ inputs.maven-release-version-number}} DOCKER_REGISTRY_ID: ${{ inputs.docker-registry-id }} DOCKER_REGISTRY_USERNAME: ${{ inputs.docker-registry-username }} DOCKER_REGISTRY_PASSWORD: ${{ inputs.docker-registry-password }} M2_HOME_FOLDER: ${{ inputs.m2-home-folder}} GIT_RELEASE_BOT_NAME: ${{ inputs.git-release-bot-name }} GIT_RELEASE_BOT_EMAIL: ${{ inputs.git-release-bot-email }} SKIP_GIT_SANITY_CHECK: ${{ inputs.git-skip-sanity-check }} SKIP_PERFORM: ${{ inputs.skip-perform }} GITREPO_ACCESS_TOKEN: ${{ inputs.access-token }} VERSION_MAJOR: ${{ inputs.version-major }} VERSION_MINOR: ${{ inputs.version-minor }} VERSION_PATCH: ${{ inputs.version-patch }} RELEASE_BRANCH_NAME: ${{ inputs.release-branch-name }} ================================================ FILE: release-github-actions.sh ================================================ #!/usr/bin/env bash export CI_COMMIT_SHA="${GITHUB_SHA}" export CI_COMMIT_REF_NAME="${GITHUB_REF}" release.sh