Process Integration and Artifact Management for GitHub

Since R2023b. Recommended over Integrate Process into GitHub.

This example uses:

You can set up continuous integration (CI) for your model-based design projects in GitHub® by using the CI Support Package for Simulink. The support package allows you to run pipelines of tasks in GitHub Actions and manage artifacts by using network storage, JFrog Artifactory, Amazon S3™, or Azure® Blob storage.

This example shows how to:

  1. Set up a GitHub repository and GitHub runner for running processes.

  2. Define tasks for your project by using an example process model.

  3. Connect your MATLAB® project to a remote GitHub repository for source control integration.

  4. Generate a CI pipeline file and supporting files that enable you to run an GitHub Actions workflow for your specific process model and pipeline settings.

This example shows the recommended way to integrate your process into GitHub by using pipeline generator version 2, which has enhanced file propagation and artifact management. For alternatives, see Approaches to Running Processes in CI.

Set Up GitHub Project and Runner

To set up the CI system, you must set up a source-controlled remote repository where you store your project and a build agent that can run your pipeline on that repository. Typically, the build agent is a self-hosted build agent rather than a cloud-hosted build agent. 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 GitHub repository and enable GitHub Actions. See the GitHub documentation for Quickstart for repositories.

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

  3. Install the required products and tools on your build agent by using one of these approaches:

    • Option 1: Manually Install Products and Tools on Build Agent

      1. Install MATLAB, Simulink®, Simulink Check™, the CI Support Package for Simulink, and any other products that your process requires. For more information, see Tips for Setting Up CI Agents.

      2. Install Python® with the alias python3 available in your system path. The pipeline generator was developed with Python 3.11. Optionally, to add colors to CI job logs, you can also install the Python library colorlog.

      3. By default, the pipeline generator assumes that you have a shared network storage location for artifacts. However, if you plan to use an external artifact management system instead, make sure to install the CLI tool for your chosen system:

    • Option 2: Use Prebuilt Docker® Image

      You can simplify and automate build agent setup by using a prebuilt Docker image as your build environment. You can create a Docker image for pipeline generation by following the steps in Build and Use Docker Image to Run Processes. The image includes the CI support package, Python, artifact management CLIs, and other CI tools for pipeline generation.

Before you continue, make sure MATLAB is available on the system PATH so the build agent can access MATLAB.

Connect MATLAB Project to GitHub

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

  1. For this example, create a copy of the Process Advisor example project for GitHub.

    processAdvisorGitHubExampleStart

    This example project contains:

    • A process model, processmodel.m, that defines a process with common model-based design tasks. For information on how to customize a template process model for your development and verification workflow, see Customize Your Process Model.

    • An example workflow file, simulink_pipeline.yml. In this example, you generate a new, customized version of the simulink_pipeline.yml pipeline file that provides the GitHub Actions workflow information about your specific project and process.

  2. Connect your project, remote repository, and CI platform by adding the remote URL to your local repository. For more information, see Share Git Repository to Remote. Typically, a remote URL has the format, https://github.com/user/repo.git.

Generate Pipeline File and Supporting Files

You generate the GitHub Actions workflow file and its supporting files by using the pipeline generator in MATLAB.

  1. Configure the pipeline generation options by creating a padv.pipeline.GitHubOptions object and specifying the GeneratorVersion property as 2.

    op = padv.pipeline.GitHubOptions(GeneratorVersion=2);

  2. Configure the pipeline generator to use your GitHub runner, MATLAB version, and support package installation by specifying the properties RunnerLabel, MatlabInstallationLocation, and SupportPackageRoot.

    op.RunnerLabels = "padv_demo_ci";
op.MatlabInstallationLocation = "C:/Program Files/MATLAB/R2025a/bin";
op.SupportPackageRoot = "C:\\ProgramData\\MATLAB\\SupportPackages\\R2025a\\bin";

  3. Choose where to store your pipeline artifacts by setting the ArtifactServiceMode property. Each artifact storage approach has its own specific configuration requirements as shown in ArtifactServiceMode. Depending on which artifact storage approach you choose, you need to specify additional properties and GitHub secrets. See the GitHub documentation for Using secrets in GitHub Actions.

    Artifact Storage ApproachExample CodeRequired Credentials

    Network storage

    op.ArtifactServiceMode = "network";
op.NetworkStoragePath = "/artifactManagement/cacheStorage";

    None.

    JFrog Artifactory

    op.ArtifactServiceMode = "jfrog";
op.ArtifactoryUrl = "http://localhost:8082/artifactory";
op.ArtifactoryRepoName = "example-repo-local";

    Store the JFrog API token as a secret named ARTIFACTORY_API_TOKEN_SECRET in GitHub.

    Amazon S3

    op.ArtifactServiceMode = "s3";
op.S3BucketName = "my-artifacts-bucket";
op.S3AwsAccessKeyID = "AKIAIOSFODNN7EXAMPLE";

    Store the Amazon S3 access key as a secret named S3_AWS_SECRET_ACCESS_KEY_SECRET in GitHub.

    Azure Blob

    op.ArtifactServiceMode = "azure_blob";
op.AzContainerName = "mycontainer";

    Store the Azure storage account connection string as a secret named AZ_CONNECTION_STRING_SECRET in GitHub.

  4. Optionally, if you want to runs tasks inside a containerized environment, such as a Docker container, uncomment and specify the properties RunnerType and ImageTag. For example:

    op.RunnerType = "container";
op.ImageTag = 'my-docker-image-name';
    Depending on your setup, you might need to make adjustments to the MatlabLaunchCmd, MatlabStartupOptions, AddBatchStartupOption properties. For example:
    % Docker image settings
op.MatlabLaunchCmd = "xvfb-run -a matlab -batch"; 
op.MatlabStartupOptions = "";
op.AddBatchStartupOption = false;

  5. Optionally, you can customize other pipeline generator behaviors by modifying the other properties of the padv.pipeline.GitHubOptions object. For example, by default, the pipeline generator runs the process in a single stage. To have a pipeline with a stage for each task iteration, you can specify:

    op.PipelineArchitecture = "SerialStages";

    Note

    If you decide to use the IndependentModelPipelines architecture to generate code and perform code analysis tasks in parallel, you must either switch to using the template parallel process model or update your existing process as shown in Considerations for Parallel Code Generation. These updates allow the tasks in your pipeline to properly handle shared utilities and code generated across parallel jobs.

  6. Generate the pipeline file and supporting files by calling the padv.pipeline.generatePipeline function on your padv.pipeline.GitHubOptions object.

    padv.pipeline.generatePipeline(op)
    The pipeline generator generates these files:

    • In the derived\pipeline directory:

      • ir_dag.json — Pipeline data file that stores information about the task iterations and pipeline options for your specific project and process.

      • simulink_pipeline.yml — Pipeline file that defines a GitHub Actions workflow.

    • In the .github\workflows directory:

      • generic-job.yml — Pipeline template file.

    The generated pipeline file uses the following GitHub Actions, available from the GitHub Marketplace:

    • actions/checkout@v4

    • actions/download-artifact@v4

    • matlab-actions/run-command@v2

    • actions/upload-artifact@v4

Use Generated Files to Define GitHub Actions Workflow

  1. Copy the generated pipeline file, simulink_pipeline.yml, and data file, ir_dag.json, from derived\pipeline to .github\workflows.

    source = fullfile(currentProject().RootFolder,"derived","pipeline");
dest = fullfile(currentProject().RootFolder,".github","workflows");
copyfile(source,dest);

  2. In the .github/workflows folder, edit the simulink_pipeline.yml file to specify the paths to the generated files.

    For this example, replace "/path/to/ir_dag.json" and "/path/to/simulink_pipeline.yml" with ".github/workflows/ir_dag.json" and ".github/workflows/simulink_pipeline.yml" respectively.

    cp ".github/workflows/ir_dag.json" "${{env.MW_RELATIVE_PROJECT_PATH}}${{env.MW_PIPELINE_GEN_DIRECTORY}}/" 
cp ".github/workflows/simulink_pipeline.yml" "${{env.MW_RELATIVE_PROJECT_PATH}}${{env.MW_PIPELINE_GEN_DIRECTORY}}/"

  3. Add the generated files to source control, then commit and push your changes.

    By default, simulink_pipeline.yml expects generic-job.yml to be in the .github\workflows directory. If you want to place the generic-job.yml file elsewhere in your repository, set the TemplatePath property in your padv.pipeline.GitHubOptions object and regenerate the pipeline files.

  4. In GitHub, configure your pipeline to use the existing simulink_pipeline.yml file from the repository root as your Azure Pipelines YAML file.

  5. Commit and push your changes to the repository.

After you commit your changes, GitHub automatically runs the workflow file, simulink_pipeline.yml. You can see your process running in GitHub when you click on the Actions tab. For information on the workflow results, see the GitHub documentation for Viewing your workflow results.

See Also

|

Topics