Enhanced Process Integration and Artifact Management for GitHub

Since R2023b. Recommended over Integrate Process into GitHub.

This example uses:

You can create and run pipelines of tasks in GitHub® Actions and manage artifacts with JFrog Artifactory by using the CI Support Package for Simulink.

In this example, you connect a project to GitHub and generate a GitHub Actions pipeline file by using the pipeline generator. You can specify the pipeline generator options to create pipelines that separate tasks into parallel jobs, customize other pipeline behaviors, and integrate with JFrog Artifactory.

This example shows the recommended way to integrate your process into GitHub by using pipeline generator version 2. Pipeline generator version 2 is recommended for enhanced file propagation and artifact management capabilities. Alternatively, you can run your process as a build step or use pipeline generator version 1. For more information, see Approaches to Running Processes in CI.

Note

For R2025a, this functionality will be available in a future release of the support package.

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 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 the required MathWorks® products on your GitHub runner. At a minimum, the pipeline generator requires MATLAB®, Simulink®, Simulink Check™, and the CI Support Package for Simulink. You must also install any other products that your process uses. For information on licensing considerations, Docker® containers, and virtual displays, see Tips for Setting Up CI Agents.

    Make sure that your GitHub runner machine can access and run MATLAB before you continue.

  4. Install Python® on your GitHub runner. The pipeline generator was developed with Python 3.11.3. Optionally, to allow the pipeline generator to add colors to CI job logs, you can also install the Python library colorlog.

  5. In the GitHub settings for your repository, add these repository variables. For information on how to define repository variables, see the GitHub documentation for Defining configuration variables.

    You can choose to manage your pipeline artifacts on either a network drive or JFrog Artifactory.

    For this example, start by using a network drive location by setting the repository variable ARTIFACT_SERVICE_MODE to network.

    Repository VariableDescription
    ARTIFACT_SERVICE_MODE

    Artifact storage approach that you want to use, specified as either network or jfrog.

    NETWORK_STORAGE_PATH

    Path for storing artifacts on a network storage location when the ARTIFACT_SERVICE_MODE is set to network.

    For example, C:/Data/artifactManagement.

    PATH_TO_MATLAB

    Path to bin folder for MATLAB installation on GitHub runner.

    For example, C:/Program Files/MATLAB/R2024b/bin.

    PYTHON_ALIAS

    Alias for Python on the GitHub runner.

    For example, python3.

    RUNNER_LABEL

    Label for GitHub runner.

    For example, padv_demo_ci.

    SUPPORT_PACKAGE_ROOT

    Root folder of support packages on the GitHub runner. You can find installation directory by using the function matlabshared.supportpkg.getSupportPackageRoot in MATLAB on your GitHub runner.

    For example, C:\\ProgramData\\MATLAB\\SupportPackages\\R2024b\\bin.

Using JFrog Artifactory

To use JFrog Artifactory as your artifact management system instead of a network drive location:

  1. Create an API token in JFrog and add the token to the GitHub secrets for your repository. For this example, name the secret ARTIFACTORY_API_TOKEN_SECRET. See the JFrog documentation for Access Tokens and the GitHub documentation for Using secrets in GitHub Actions.

  2. Set the repository variable ARTIFACT_SERVICE_MODE to jfrog.

  3. Add these additional repository variables.

    Configuration VariableDescription

    ARTIFACTORY_URL

    URL for the JFrog Artifactory server that manages the artifacts.

    For example, http://localhost:8082/artifactory.

    ARTIFACTORY_REPO_NAME

    Name of the JFrog Artifactory repository where artifacts are stored.

    For example, example-repo-local.

    ARTIFACTORY_API_TOKEN

    API token for authenticating with JFrog Artifactory, retrieved from GitHub secrets.

    For this example, ARTIFACTORY_API_TOKEN_SECRET.

 JFrog Artifactory Versions

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

    The project opens an example workflow file simulink_pipeline.yml. In this example, you generate a new, customized version of the simulink_pipeline.yml pipeline and a pipeline data file, ir_dag.json, that provides the GitHub Actions workflow information about your specific project and process.

  2. Connect the project to the remote repository. 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 MATLAB Projects.

Generate Pipeline File and Pipeline Data 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 GeneratorVersion property as 2.

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

  2. You can customize how the pipeline generator creates your pipeline file by modifying the other properties of the object. For example, you can create a padv.pipeline.GitHubOptions object for a GitHub runner that uses a MATLAB installation at C:/Program Files/MATLAB/R2024b/bin and generates a report inside the results folder for the project.

    GitHubOptions.MatlabInstallationLocation = "C:/Program Files/MATLAB/R2024b/bin";
GitHubOptions.ReportPath = "$PROJECTROOT$/04_Results/ProcessAdvisorReport";

    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. 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.

  3. Generate the pipeline configuration files by calling the padv.pipeline.generatePipeline function on your padv.pipeline.GitHubOptions object.

    padv.pipeline.generatePipeline(GitHubOptions)
    The pipeline generator generates two files in the derived/pipeline folder:

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

    • 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 uses this file when executing the workflow.

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

    • checkout@v4

    • upload-artifact@v4

Use Generated Files to Define GitHub Actions Workflow

To set up pipeline generation, your project must have these files checked into source control:

  • In the .github/actions folder:

    • job-execute — Custom action, available in the example project

    • job-upload-artifacts — Custom action, available in the example project

  • In the .github/workflows folder:

    • generic-job.yml — Custom workflow file, available in the example project

    • simulink_pipeline.yml — Generated pipeline file

  • ir_dag.json — Generated pipeline data file

The example project already has a .github/workflows folder, workflow file generic-job.yml, and .github/actions folder with custom actions job-execute and job-upload-artifacts. For information on GitHub Actions workflows, see the GitHub documentation for Quickstart for GitHub Actions.

  1. Copy the generated files, simulink_pipeline.yml and 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 scm/.github/workflows/ir_dag.json scm/ir_dag.json
          cp scm/.github/workflows/simulink_pipeline.yml scm/simulink_pipeline.yml

  3. 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