CI Build

Describing the building workflow

Trigger the workflow and how it works

Commit and push changes to any branch. The CI Worflow is automatically triggered and starts the building process. An Ubuntu based container is created where all our commands will setup the process. A container is dedicated to only 1 job which has multiple steps. Therefore, the build process has its own job as described in the .yml. The same goes for the test and deploy jobs.

jobs:
  build:
    runs-on: ubuntu-latest

Building process

1. Cloning repositories

We download all required repositories to build the image. This is done using a GitHub provided actions that checkouts (clones and switches) to specified repositories inside our container. The benefits of using this action is that GitHub uses its own ressources to (nearly) instantly clone the repository, whereas cloning would take a few minutes.

A checkout action looks like the following:

    - name: Checkout riseclipse-metamodel-nsd2016
      uses: actions/checkout@v2
      with:
        path: riseclipse-metamodel-nsd2016
        repository: RiseClipse/riseclipse-metamodel-nsd2016
        ref: use-up-to-date-components

2. Installing maven

Once again, GitHub provides a specific action that automatically setups a maven environment for us using this:

    - name: Set up JDK 11
      uses: actions/setup-java@v2
      with:
        java-version: '11'
        distribution: 'adopt'
        cache: maven

3. Build using maven

Now that everything is setup, we can start the build using a simple maven command: mvn install. Priorly, we just ensure our current working directory is at the right place, which for this project is:
riseclipse-developer/fr.centralesupelec.edf.riseclipse.developer.maven.validator.scl

This corresponds to this step in the job:

    - name: Build with Maven 
      run: |
        cd riseclipse-developer
        cd fr.centralesupelec.edf.riseclipse.developer.maven.validator.scl
        mvn install

4. Generated artefact

The maven plugin is configured to generate some .jar artefacts which are our usable RiseClipse tools.

In order to distribute the .jar files, they need to be formatted. The Rename artefacts and zip them all renames the files to more friendly names and places to deal with in the CI, and create a ZIP of them.

We now have to ensure the artefacts are available for the nexts jobs of our workflow using a GitHub provided actions that uploads the artifact.

    - name: Upload artifact
      uses: actions/upload-artifact@v2
      with:
        name: RiseClipse-cli.jar
        path: ${{ github.workspace }}/RiseClipse-Validator-SCL-CLI.jar

The previous action is used for each artifact.

At this step which is the end of the build job, the .jar files can be downloaded as artefacts of this workflow in the Actions section of the repository, and are also available for next jobs.

Customize the CI Building workflow

Note that every changes should be apply inside the .github/workflow/mvn-cli.yml file.

Change build triggers

Currently, the workflow is triggered whenever you commit to any branch that has the workflow setup (in other words, it has the .github/workflow folder).
If you wish to change this behaviour, you have to modify the on attribute to add events that will trigger the workflow.
For instance, you can only trigger the workflow when you commit to a specific branch using the branches attribute. You can also trigger only when you do pull_request, push or tag commits

on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  # Also trigger on page_build, as well as release created events
  page_build:
  release:
    types: # This configuration does not affect the page_build event above
      - created

You can learn more about how to use events at GitHub's official documentation for Events and triggers

Change maven version

If you need to update or change the maven tool version, just change the version number in the action that setups the maven environment:

    - name: Set up JDK 11
      uses: actions/setup-java@v2
      with:
        java-version: '11' # <== YOUR VERSION HERE
        distribution: 'adopt' # <== YOUR DISTRIBUTION SOURCE HERE
        cache: maven

Change container image

If you want a specific image of the container that builds the image, change the based-on attribute:

    runs-on: ubuntu-latest # <== YOUR IMAGE HERE

Select the artefact to upload

If you made changes in the maven config that generates the .jar to another folder, just change the path in the upload artifact step:

    - name: Upload artifact
      uses: actions/upload-artifact@v2
      with:
        name: RiseClipse-cli.jar
        # YOUR NEW PATH BELOW
        path: ${{ github.workspace }}/RiseClipse-Validator-SCL-CLI.jar

Please note that by default, all path are relative to $GITHUB_WORKSPACE.

Add dependent repositories

If the maven building process requires new repositories to generate the image, just add a checkout action targeting your repository:

    - name: Checkout riseclipse-main
      uses: actions/checkout@v2
      with:
        path: riseclipse-main # <== FOLDER NAME IN THE CONTAINER
        repository: RiseClipse/riseclipse-main # <== REPOSITORY NAME (don't forget to specify the owner) 
        ref: use-up-to-date-components # <== BRANCH NAME