Main Content

Attach Model Comparison Report to GitLab Merge Requests

Open Live Script

This example shows how to automate the generation of Simulink® model diffs for GitLab® merge requests and push events using GitLab CI/CD. Automatically attach the comparison reports to merge requests or push events for easy viewing outside of MATLAB® and Simulink.

Prerequisites

  1. Open the example to download the two MATLAB code files, diffGitLab_mergerequest.m and diffGitLab_push.m, and the YAML file .gitlab_ci.yml.

  2. The jobs, defined in .gitlab_ci.yml, use a self-hosted runner. Using a self-hosted runner enables you to customize hardware. To add a self-hosted runner to your repository, follow the instructions at https://docs.gitlab.com/ee/tutorials/create_register_first_runner/#create-and-register-a-project-runner.

  3. Ensure that you have MATLAB and Simulink installed on the self-hosted runner you are using.

Alternatively, if you prefer to use a GitLab-hosted runner, update the .matlab_defaults block in the provided .gitlab_ci.yml file. GitLab-hosted runners implement a MATLAB Container on Docker Hub to run your build using MATLAB R2020b or a later release. For more information, see https://github.com/mathworks/matlab-gitlab-ci-template?tab=readme-ov-file#use-matlab-with-gitlab-cicd.

Attach Diff Reports Using GitLab CI/CD

GitLab CI/CD allows you to automate workflows that you define in YAML files. This example shows how to set up the workflows to trigger on push and merge requests to the main branch on GitLab. These workflows use the MATLAB code files to:

  1. Get the list of modified model files and their ancestors using Git™ commands.

  2. Compare every modified model to its ancestor and publish an HTML comparison report using the visdiff function. To conduct peer review of changes, use the DOCX file format when publishing the reports. Using DOCX files allows reviewers to leave detailed comments on different blocks or parameters.

  3. Upload all model comparison reports to the job when it is complete.

  4. Run all the project tests.

To set up the pipeline on GitLab, add the MATLAB code files to your repository by selecting + > Upload file. Then, clone the repository to create a new copy.

Now, when you push your commits to the main branch or create a merge request to merge a development branch with main, it triggers the pipeline you set up. When the job is successful, contributors and reviewers can access the model comparison reports using the Download artifacts button.

Passed job in GitLab with the mouse pointing to the Download artifacts button positioned to the right of the job

Notes

  • To include screenshots in the comparison report, your runner must have a display. On Linux® operating systems, if your runner does not have a display, you can use xvfb-run to run commands on a display server that implements the X11 display server protocol.

  • Starting in R2022b, you can use the Comparison Tool to generate comparison reports with no screenshots when running jobs on a no-display machine.

Related Topics