CI Release

Overview of the release job

The file

The GitHub Actions interface

The GitHub Actions documentation

The release job is constituted of 3 types of steps. It is run after the build and test jobs, and only when a tag is pushed.

  deploy:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
    needs: [build, test]

Get the artifact

The step of getting an artifact is currently achieved by fetching the artifact previously build in the build job. Since it is a different job, it has to be downloaded with the action actions/download-artifact@master, that is the conterpart of the action actions/upload-artifact@v2 (used in the build job). The .jar files are then available at the same path, as if they persisted from the build job.

    - name: Download artifact .jar
      uses: actions/download-artifact@master
      with:
        name: RiseClipse-cli.jar
        path: ${{ github.workspace }}

Create the release

A Github release is constituted of :

• An ID
• A name
• An associated tag on the repository
• Some options
• Some assets

This step creates the release with the parameters except the files. It will allow the following steps to refer to the release with the ID. The CI uses the action actions/create-release@v1 to achieve this step. It also needs a token, but this token is available in the secrets by default. Since the release job only triggers on tags, the trigger tag is used as release tag.

    - name: Create Release
      id: create_release
      uses: actions/create-release@v1
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        tag_name: ${{github.ref_name}}
        release_name: Release ${{github.ref_name}}
        draft: true
        prerelease: false

Upload the assets

For each asset (in this case the .jar files), a step using the action actions/upload-release-asset@v1 is needed. It uses the previously created, and upload the artifacts to its url. If the CI succeeds, the release will be available on the repository website.

    - name: Upload Release Asset
      id: upload-release-asset 
      uses: actions/upload-release-asset@v1
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        upload_url: ${{ steps.create_release.outputs.upload_url }}
        asset_path: ${{ github.workspace }}/RiseClipse-cli.jar
        asset_name: RiseClipse-cli.jar
        asset_content_type: application/jar

Customisation of the release job

The current job used has been detailed in the previous section, but it can be customized if needed

Job configuration

The job is a list of ordered steps. The current order is detailed before, but it can be changed. The order of execution of the steps is the order of the list in the YAML file.

Steps configuration

A Github Action job is constituted of a name and an action thas has settings. The following sections will detail what useful tweaks could be used to customize the jobs.

Get the artifact

In this step, you can customize the name and the path of the artifact. The name must match the one of the corresponding counterpart action actions/upload-artifact@v2. The path also can be customized, but there is generally no need to do so, because it doesn’t appear in the final products of the CI.

Create the release

In this step, some parameters are interesting to customize.

• tag_name: generally a version tag, but can be expanded or changed. It also could be set automatically to match a version string in the project and then generating a tag, instead of fetching the version from the git tag.
• release_name: Just a matter of style
• draft: This parameter set the release as a draft instead of published, it allows to delete it easily or to edit it.
• prerelease: This parameter is a flag mainly used to indicate the stability of the release

There is a lot of others settings, that are listed on (the official documentation)[https://github.com/actions/create-release]

Upload the assets

This step add the files to the release. It has to be called for every file.

• upload_url: This parameter receive an upload url to the release. Here, it neeeds to be set on the variable pointing on the previously created release.
• asset_path: The path to the file
• asset_name: The name of the file for when it is downloaded. The parameter asset_content_type defines the Media type of the file, so in this CI, it should stay on application/jar.

A list can be found on (the official documentation)[https://github.com/marketplace/actions/github-upload-release-artifacts]