Main Content

Simulink Model Comparison for 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 YAML files, use a self-hosted runner. 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.

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.

    Tip

    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.

Related Topics