Main Content

Integrate Process into GitHub

This example uses:

You can define a process for your team and set up your CI system to run the tasks in that process as a pipeline in CI using the CI/CD Automation for Simulink Check support package.

In this example, you connect a project to GitHub® and generate a GitHub Actions workflow file for the project and its process model by using the pipeline generator. You can specify the pipeline generator options to create pipelines that separate tasks into different jobs and use other custom pipeline behaviors.

This example shows the recommended way to use your process in GitHub. Alternatively, you can manually author a GitHub Actions workflow file that opens your project and runs your process. For more information, Approaches to Running Processes in CI.

Set Up GitHub Project and Runner

To set up the CI system, you need to set up a source-controlled remote repository where you store your project and a CI agent machine that can run your pipeline on that repository. For this example, you can use GitHub as both your remote repository and CI system, and then create a self-hosted GitHub runner to run your pipelines.

  1. In GitHub, create a private GitHub repository. For information, see Quickstart for repositories in the GitHub documentation. Make sure GitHub Actions is enabled for your repository.

  2. Create a self-hosted runner. See the GitHub documentation for Adding self-hosted runners.

  3. Install MATLAB®, Simulink®, Simulink Check™, the CI/CD Automation for Simulink Check support package, and any other products that your process requires on the machine that your GitHub runner is running on. Make sure that your GitHub runner machine can access and run MATLAB before you continue.

For information on licensing considerations, Docker® containers, and virtual displays, see Tips for Setting Up CI Agents.

Connect MATLAB Project to GitHub

You need to connect your MATLAB project to your remote repository so that you can push your changes to the remote GitHub repository and allow GitHub to automate a CI pipeline for the project.

  1. Open a project in MATLAB. For this example, open an example project that uses the process defined by an example process model.

    processAdvisorExampleStart

    The process model, processmodel.m, is at the root of the project and defines a process with common model-based design tasks. You can use the Process Advisor app to run the tasks in the process on your local machine. For information on how to create and customize a process model for your development and verification workflow, see Customize Your Process Model.

  2. On the Project tab, in the Source Control section, click Remote and specify the URL for the remote origin in GitHub where your repository is hosted. For example, https://github.com/user/repo.git.

    The example project is already set up to use local Git™ source control. For information on how to use source control with your projects, see Use Source Control with Projects.

Generate Pipeline Configuration File

You generate the GitHub Actions workflow file by using the pipeline generator.

  1. In MATLAB, configure the pipeline generation options by creating a padv.pipeline.GitHubOptions object and specifying the location of your MATLAB installation for your runner.

    The padv.pipeline.GitHubOptions object stores the options for the pipeline generator. You can modify the other properties of the object to customize how the pipeline generator creates your pipeline configuration file. For example, you can create a padv.pipeline.GitHubOptions object for a GitHub runner that uses a MATLAB installation at /opt/matlab/r2023a.

    GitHubOptions = padv.pipeline.GitHubOptions
GitHubOptions.MatlabInstallationLocation = "/opt/matlab/r2023a";

    By default, GitHubOptions specifies a SingleStage pipeline architecture that runs all the tasks in the process within a single stage in CI. To change the number of stages or the grouping of tasks in the CI pipeline, specify the PipelineArchitecture property of your padv.pipeline.GitHubOptions object.

  2. Generate a pipeline configuration file for your project by calling the padv.pipeline.generatePipeline function on your padv.pipeline.GitHubOptions object.

    padv.pipeline.generatePipeline(GitHubOptions)

    By default, the generated pipeline configuration file is named simulink_pipeline.yml and is located under the project root, in the subfolder derived > pipeline.

    The generated pipeline configuration file uses the following GitHub Actions:

    • checkout@v3

    • cache@v3

    • upload-artifact@v3

    • download-artifact@v3

Use Pipeline Configuration File in GitHub Actions Workflow

To use the generated pipeline configuration file in your GitHub repository, you need to create a workflow and update the workflow file.

  1. In GitHub, create a GitHub Actions workflow by creating a directory .github/workflows and creating a new YAML file github-actions-demo.yml. See https://docs.github.com/en/actions/quickstart#creating-your-first-workflow.

  2. In MATLAB, open your generated pipeline configuration file and copy the file contents.

  3. In GitHub, paste the contents of simulink_pipeline.yml inside the github-actions-demo.yml file.

  4. Check the new github-actions-demo.yml file into your repository by committing the changes and creating a pull request.

After you commit your changes, GitHub automatically runs the workflow file, github-actions-demo.yml. You can see your process running when you click on the Actions tab. For information on the GitHub workflow results, see https://docs.github.com/en/actions/quickstart#viewing-your-workflow-results.

See Also

|

Related Topics