# 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.

```yaml
  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:

1. *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.
2. *Generate*: generates dynamically the YAML configuration file for the child pipeline.
3. *Triggers*: starts the child pipeline using the dynamically-generated YAML file.
4. *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.

<img style="float: middle;" width="700" src="figures/main.png">

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

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

<img style="float: middle;" width="700" src="figures/child.png">

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

:::{admonition} Child pipeline status do not appear in the main pipeline page
:class: warning

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.

<img style="float: middle;" width="700" src="figures/pipeline_page.png">


<img style="float: middle;" width="700" src="figures/downstream.png">
:::

:::{admonition} If child pipeline passes after a retry, the main pipeline remains in the fail status
:class: warning

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.
:::