Full Code of qcastel/github-actions-maven-release for AI

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>
        <connection>scm:git:${project.scm.url}</connection>
        <developerConnection>scm:git:${project.scm.url}</developerConnection>
        <url>git@github.com:idhub-io/idhub-api.git</url>
        <tag>HEAD</tag>
    </scm>
```
- Using HTTPS URL
```xml
	<scm>
        <connection>scm:git:${project.scm.url}</connection>
        <developerConnection>scm:git:${project.scm.url}</developerConnection>
		<url>https://github.com/YOUR_REPO.git</url>
		<tag>HEAD</tag>
	</scm>
```

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
    <plugin>
        <artifactId>maven-release-plugin</artifactId>
        <version>XXX</version>
        <configuration>
            <scmCommentPrefix>[ci skip]</scmCommentPrefix>
        </configuration>
    </plugin>
```

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
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-gpg-plugin</artifactId>
    <version>1.6</version>
    <configuration>
        <skip>true</skip>
    </configuration>
</plugin>
```

### 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 <<EOF
 %no-protection
 Key-Type: default
 Subkey-Type: default
 Name-Real: bot
 Name-Email: bot@idhub.io
 Expire-Date: 0
EOF
gpg --batch --gen-key genkey-batch
```

Note: Don't exit the docker container as we are not done yet.


### Get the KID

You can get the key ID doing the following:

```bash
gpg --list-secret-keys --keyid-format LONG

sec   rsa2048/3EFC3104C0088B08 2019-11-28 [SC]
      CBFD9020DAC388A77C68385C3EFC3104C0088B08
uid                 [ultimate] bot-openbanking4-dev (it's the bot openbanking4.dev key) <bot@openbanking4.dev>
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