Main Content

Attach Model Comparison Report to GitHub Pull Requests

Automate the generation of Simulink® model diffs for GitHub® pull requests and push events using GitHub Actions. Automatically attach the comparison reports to the pull request or push event for easy viewing outside of MATLAB® and Simulink. Watch Simulink Model Comparison for GitHub Pull Requests (4min 46sec).

Prerequisites

  1. Download the MATLAB code and YAML files from https://github.com/mathworks/Simulink-Model-Comparison-for-GitHub-Pull-Requests.

  2. Ensure that GitHub Actions is enabled for your repository.

  3. The actions, defined in the Diff_runTests_push.yml and Diff_runTests_pullrequest.yml files, use a self-hosted runner. Using a self-hosted runner enables you to keep your repository private. To add a self-hosted runner to your repository, follow the instructions at https://docs.github.com/en/actions/hosting-your-own-runners.

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

Alternatively, if you prefer to use a GitHub-hosted runner, use the actions defined in the githubrunner_push.yml and githubrunner_pullrequest.yml files instead.

Attach Diff Reports Using GitHub Actions

GitHub Actions allows you to automate workflows that you define in YAML files. This example shows how to set up the workflows to be triggered on push and pull request to the main branch on GitHub. 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 visdiff. To peer review changes, use the DOCX file format instead of HTML 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 workflows on GitHub:

  1. Add the MATLAB code files to your repository. Select Add file > Upload and upload the files. Then, click Commit Changes.

  2. Create the new workflows:

    1. On the Actions tab, click set up a workflow yourself.

      GitHub stores all workflows in the .github/workflows folder. If it does not exist already, GitHub automatically creates the .github/workflows folder in your repository.

    2. Copy the content of one of the YAML files you downloaded, for example, Diff_runTests_pullrequest.yml, and paste it in the Edit new file field.

    3. Rename the file and click Start commit > Commit new file.

    4. Repeat the steps for the second YAML file you downloaded.

    Alternatively, if you already have a .github/workflows folder in your repository, upload the YAML files to .github/workflows and commit the changes.

Now, when you push your commits to the main branch or create a pull request to merge a development branch with main, it triggers the workflows you set up. When the job is successful, contributors and reviewers can access the model comparison reports in the Artifacts section of each job.

Notes

  • Including screenshots in the comparison report requires your runner to have a display. On Linux® operating systems, if your runner does not have a display, you can use one of the following workarounds in your YAML files:

    • Start a display server before the "Compare Models to Ancestors" step. For an example, see the "Start Display Server" step in the githubrunner_pullrequest.yml file.

    • 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