Main Content

Integrate Process into Jenkins

This example uses:

You can define and run your development and verification process as a pipeline in Jenkins® by using the CI/CD Automation for Simulink Check support package. You define and configure your pipeline by using a Jenkinsfile that you store in your project. The Jenkinsfile can configure different parts of your CI/CD jobs including the stages of the job, the label for the Jenkins agent that executes the pipeline, the script that the agent executes, and artifacts you want to attach to a successful job. The support package provides a template Jenkinsfile that you can reconfigure and use to run your process. The template file uses the pipeline generator to automatically generate pipelines for you, so that you do not need to manually update pipeline configuration files when you make changes to the tasks and artifacts in your project.

This example shows the recommended way to use your process in Jenkins. Alternatively, you can run your process as a build step. For more information, Approaches to Running Processes in CI.

Set Up Jenkins

  1. Install Jenkins. See the Jenkins documentation for Installing Jenkins.

  2. Install the following plugins for Jenkins:

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

  4. Configure at least one executor on your Jenkins instance. Executors control the number of concurrent tasks or builds Jenkins can run. The number of required executors depends on the pipeline architecture that you select. For the serial pipeline architectures, you must have at least one executor configured and available to load, generate, and execute your pipeline using the pipeline generator. For the parallel pipeline architecture, IndependentModelPipelines, you need two executors. For more information, see PipelineArchitecture. For information on how to define Jenkins executors, see the Jenkins documentation on Managing Nodes.

  5. Create a new Jenkins pipeline project, but leave your Jenkinsfile pipeline definition empty for now. See the Jenkins documentation for Getting started with Pipeline. Instead of manually writing a Jenkinsfile, you reconfigure the template Jenkinsfile, add that file to your MATLAB project, and use that file to define your pipelines as shown in Configure and Use Jenkinsfile Template.

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

Connect Jenkins Project to Repository

To set up your CI system, you need to set up a source-controlled remote repository where you store your MATLAB project and you need to connect that repository to your Jenkins project.

For this example, you can set up a GitLab® repository and connect that repository to Jenkins.

  1. Set up a remote GitLab repository by creating a new blank project. See the GitLab documentation for Create a project.

  2. Connect your MATLAB project to the remote repository.

    For this example, you can open the Process Advisor example project processAdvisorExampleStart and, on the Project tab, in the Source Control section, click Remote to specify the URL for the remote origin in GitLab where your repository is hosted. For example, https://gitlab.com/gitlab-org/gitlab.git.

    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. You can copy the default process model template into a project by entering createprocess(Template = "default") at the command line. For information on how to customize a template process model for your development and verification workflow, see Customize Your Process Model.

  3. Configure GitLab integration with Jenkins. See GitLab documentation for Jenkins integration.

Configure and Use Jenkinsfile Template

For Jenkins, you can define your CI pipelines by using a Jenkinsfile. The support package includes a Jenkinsfile template that you can reconfigure and then use to automatically generate pipelines.

  1. In your MATLAB project, change your current folder to your project root and copy the template Jenkinsfile file into your project. The template Jenkinsfile is generic and can work with any project.

    exampleJenkinsfile = fullfile(...
matlabshared.supportpkg.getSupportPackageRoot,...
"toolbox","padv","samples","Jenkinsfile_pipeline_gen");

copyfile(exampleJenkinsfile,"Jenkinsfile")

  2. Open and inspect the template Jenkinsfile in your project. The file defines a pipeline that checks out code from a specified Git™ repository, specifies MATLAB environment information, and then uses MATLAB to generate and execute a pipeline file for your specific project and process. The template uses the pipeline generator function, padv.pipeline.generatePipeline to generate the pipeline stages and the object padv.pipeline.JenkinsOptions to specify the pipeline generation options.

  3. In the Jenkinsfile, update the file to specify the:

    • Agent label for the top-level Jenkins agent that you want to use within the node('labelName') block. For example:

      //Scripted Pipeline
node ('agent1') {

    • Git branch, credentialsId, and url for your repository. For example:

      git branch: 'testBranch', 
credentialsId: 'jenkins-common-creds', 
url: 'git://example.com/my-project.git'

    • Path to the bin directory for your MATLAB installation. For example:

      env.PATH = "C:\\Program Files\\MATLAB\\R2024b\\bin;${env.PATH}" // Windows
// env.PATH = "/usr/local/MATLAB/R2024b/bin:${env.PATH}"        // Linux
// env.PATH = "/Applications/MATLAB_R2024b.app/bin:${env.PATH}" // macOS
      withEnv(["PATH=C:\\Program Files\\MATLAB\\R2024b\\bin;${env.PATH}"]) { // Windows
// withEnv(["PATH=/usr/local/MATLAB/R2024b/bin:${env.PATH}"]) {        // Linux
// withEnv(["PATH=/Applications/MATLAB_R2024b.app/bin:${env.PATH}"]) { // macOS

    Now your Jenkinsfile file contains the information for your specific CI setup. This Jenkinsfile acts as a parent pipeline file. The other sections of the Jenkinsfile use calls to the openProject and padv.pipeline.generatePipeline functions to open your project and generate a child pipeline file for your specific project and process. The Jenkinsfile uses the load command to load the generated child pipeline file.

    Jenkinsfile with updated agent label, Git repository information, and updated paths. The Jenkinsfile also shows where the file calls the pipeline generator function.

  4. Add the Jenkinsfile to your project.

  5. Push the changes to your project to source control.

  6. Configure your Jenkins project to use the Jenkinsfile in source control.

    1. In the Pipeline section of the project configuration window, select Pipeline script from SCM from the Definition list.

    2. Select your source control system from the SCM list.

    3. Paste your repository URL into the Repository URL box.

    For more information, see Plugin Configuration Guide (GitHub).

At this point, the template file is set up to generate a Jenkins pipeline, with stages for each task in your process, the next time that you trigger a build. Optionally, you can further customize the template file to change how the pipeline generator organizes and executes the pipeline. You can dry run your tasks, have separate stages for each task iteration in the process, and specify other options by using the padv.pipeline.JenkinsOptions object in the template.

Make Optional Customizations

Optionally, you can reconfigure the template file to customize how the pipeline generator organizes and executes the pipeline. To customize the pipeline generator options, you modify the property values of the padv.pipeline.JenkinsOptions object in the template.

For example, suppose that you want to:

  • Dry run tasks to quickly validate task inputs and generate representative outputs without performing the full task operation.

  • Perform license checkouts during the dry runs to make sure that your Jenkins agent has access to the required products.

  • Have stages for each task iteration in the process.

To change how the template file generates the pipeline, you can modify the padv.pipeline.JenkinsOptions in the runMATLABCommand in the Pipeline Generation stage.

        // Requires MATLAB plugin
        stage('Pipeline Generation'){
            
            env.PATH = "C:\\Program Files\\MATLAB\\R2024b\\bin;${env.PATH}" // Windows
            // env.PATH = "/usr/local/MATLAB/R2024b/bin:${env.PATH}"        // Linux
            // env.PATH = "/Applications/MATLAB_R2024b.app/bin:${env.PATH}" // macOS
            
            /* Open the project and generate the pipeline using
            appropriate options */

            runMATLABCommand '''cp = openProject(pwd);
            rpo = padv.pipeline.RunProcessOptions;
            rpo.DryRun = true;
            rpo.DryRunLicenseCheckout = true;
            padv.pipeline.generatePipeline(...
            padv.pipeline.JenkinsOptions(...
            RunprocessCommandOptions = rpo,...
            PipelineArchitecture = padv.pipeline.Architecture.SerialStages,...
            GeneratedJenkinsFileName = "simulink_pipeline",...
            GeneratedPipelineDirectory = fullfile("derived","pipeline")));'''
        }
This example code creates a padv.pipeline.RunProcessOptions object, rpo, for customizing the behavior of the runprocess function in CI. In this case, specifying the runprocess arguments DryRun and DryRunLicenseCheckout as true. The code updates the padv.pipeline.JenkinsOptions object to use a different PipelineArchitecture, SerialStages, and use the RunprocessCommandOptions specified by rpo. For more information, see How Pipeline Generation Works.

If you modify other parts of the template file, make sure that your changes use valid Jenkins pipeline syntax. For more information, see the Jenkins documentation for Pipeline Syntax.

Generate Pipeline in Jenkins

The next time that you trigger a build, your generated pipeline contains two upstream stages in Jenkins:

  • Git_Clone — Loads your Git repository information.

  • Pipeline Generation — Automatically generates and loads a pipeline file called simulink_pipeline that defines downstream stages for your process. By default, the downstream stages include:

    • Stages for your process, organized by the PipelineArchitecture property specified in padv.pipeline.JenkinsOptions.

    • The Generate_PADV_Report stage, which generates a Process Advisor build report.

    • The stage, Collect_Artifacts, which collects build artifacts.

Diagram for an example generated CI pipeline. The parent pipeline contains two stages (Simulink Pipeline Generation and Simulink Pipeline Execution) and a child pipeline. The child pipeline contains stages that run the tasks in the process model, generate a report, and collect artifacts.

See Also

|

Related Topics