Hog Dynamic CI¶

Warning

Hog Dynamic CI is still under development.

A novel feature of the Gitlab Continuous Integration allows to generate dynamically a YAML file for the Gitlab-CI. Exploiting this feature Hog is now able to create a CI configuration for each project inside the Top directory automatically.

To use the dynamic CI simply include the hog-dynamic.yml in your .gitlab-ci.yml file.

  include:
    - project: 'hog/Hog'
      file: '/hog-dynamic.yml'
      ref: 'v0.2.1'

The Dynamic CI pipeline¶

The dynamic CI pipeline is activated for each non-Draft merge request commit and it is divided into a main pipeline and a child pipeline.

The main pipeline is composed by the following stages:

Merge: checks that all the required Hog environmental variables are set up and that the source branch is not outdated with respect to the target branch. If it is, the pipeline fails and asks the user to update the source branch.
Generate: generates dynamically the YAML configuration file for the child pipeline.
Triggers: starts the child pipeline using the dynamically-generated YAML file.
Collect: Collects all the artefacts from the child pipeline and, if activated, creates the Doxygen documentation. If EOS is used, it copies the implementation outputs and the Doxygen documentation to the EOS repository.

The child pipeline simulates, synthesises and implements the chosen HDL projects. It is composed by the following stages:

Generation_and_simulation: launches the workflow for the chosen Hog projects.
Collect: Collects all the artefacts of the previous stage.

If the HOG_CHECK_PROJVER variable is set to 1, the child pipeline will contain only jobs relative to the projects that have been modified with respect to the target branch.

Configuring the projects¶

By default the dynamic CI will create a YAML configuration for each project inside the Top folder with a full implementation and simulation. To configure the CI, a ci.conf file should be created for each project in the Top/project/ directory. Inside this file you can specify the stages to be run by the CI.

The allowed options are:

simulate_project: To run the simulation
generate_project: To run the implementation. If -synth_only option is specified, Hog will only run the synthesis for the chosen project.

Therefore an example ci.conf file looks like:

  simulate_project
  generate_project -synth_only

If you do not want the CI to run a particular project, simply create an empty ci.conf file inside the Top/project directory.

Known Issues¶

Child pipeline status do not appear in the main pipeline page

To access the child pipeline status you have to click on the status button in the first column of the Gitlab pipeline page, under CI/CD > Pipelines. Then you have to click on the Downstream box to show the child pipeline.

If child pipeline passes after a retry, the main pipeline remains in the fail status

If a child pipeline fails, the main pipeline will fail subsequently, and even if a restarted child pipeline succeed, the main pipeline would stay in a failed status. This can lead to cases where a Gitlab 504 error would make your pipeline job fail.