Enhanced Process Integration and Artifact Management for Jenkins

Since R2023b. Recommended over Integrate Process into Jenkins.

This example uses:

CI Support Package for Simulink CI Support Package for Simulink

You can create and run pipelines of tasks in Jenkins^® and manage artifacts with JFrog Artifactory by using the CI Support Package for Simulink. The support package includes two template files, a Jenkinsfile and a MATLAB^® function, that you can add to your project to automatically generate pipelines in Jenkins. You use the template files to define your Jenkins setup, configure pipeline options, and integrate with JFrog Artifactory.

This example shows the recommended way to integrate your process into Jenkins 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 Jenkins

Install Jenkins and the default suggested plugins by using the Jenkins installation documentation. If you already have Jenkins installed, make sure you have the default suggested plugins installed, including Git and Workspace Cleanup. The default suggested plugins are marked as suggested in the Jenkins platform plugins list. The pipeline generator was developed with Jenkins 2.462.2.
Install these Jenkins plugins:
- JUnit
- MATLAB
- Pipeline: Basic Steps
- Pipeline: Declarative
- If you plan on using JFrog Artifactory for artifact management, also install Credentials Binding.
For information on how to install plugins, see the Jenkins documentation Managing Plugins.
Plugin Versions
The pipeline generator was developed using these versions of the plugins:
- Git Version 5.5.2
- JUnit Version 1312.v1a_235a_b_94a_31
- MATLAB Version 2.15.0
- Pipeline: Basic Steps Version 058.vcb_fc1e3a_21a_9
- Pipeline: Declarative Version 2.2218.v56d0cda_37c72
- Workspace Cleanup Version 0.47
- Credentials Binding Version 681.vf91669a_32e45
Install the required MathWorks^® products on your Jenkins agent. At a minimum, the pipeline generator requires MATLAB, Simulink^®, Simulink Check™, and CI Support Package for Simulink. You must also install any other products that your process uses. For information on licensing considerations and virtual displays, see Tips for Setting Up CI Agents.
Make sure that your Jenkins agent can access and run MATLAB before you continue.
Install Python^® on your Jenkins agent. 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.
Configure at least two executors on your Jenkins instance. Executors control the number of concurrent tasks or builds Jenkins can run. The pipeline generator requires at least two executors: one executor to generate the pipeline and load the children stages and another executor to execute those stages. If you decide to run model tasks in parallel using the pipeline architecture IndependentModelPipelines, you need additional executors to handle each of the generated parallel pipelines. For information on how to define Jenkins executors, see the Jenkins documentation on Managing Nodes.
Create a Pipeline project in Jenkins using the default settings. For this example, you can follow the Jenkins documentation to create a basic Pipeline through the classic UI. In a later section, you return to these configuration settings to configure your Pipeline project to use the template Jenkinsfile from your source control management (SCM) system.

Connect MATLAB Project to Remote Repository

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

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

Set up a remote GitLab repository by creating a new blank project. See the GitLab documentation for Create a project.
For this example, create a copy of the Process Advisor example project for Jenkins.
```
processAdvisorJenkinsExampleStart
```
Connect the project to the remote repository. 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
```
For more information, see Use Source Control with MATLAB Projects.

Optionally, you can configure GitLab integration with Jenkins to automatically trigger Jenkins builds on code commits or merge requests. See the GitLab documentation for Jenkins integration.

Template Files in MATLAB Project

To set up pipeline generation for a project, your project must contain these two files:

Jenkinsfile_pipeline_gen — Sets up the Jenkins Pipeline, runs MATLAB, and loads the generated CI pipeline file.
generate_jenkins_pipeline.m — Configures pipeline generator options, such as the pipeline architecture and Jenkins agent labels, and generates a CI pipeline file for your specific project and process.

The template files are generic meaning you can update them to work with any project. The example project, processAdvisorJenkinsExampleStart, already contains the template files.

Update `Jenkinsfile_pipeline_gen` File

Edit the Jenkinsfile_pipeline_gen file to set environment variables according to your Jenkins setup. The file configures the Jenkins Pipeline, runs MATLAB, calls the MATLAB function generate_jenkins_pipeline.m, and loads the generated pipeline file into Jenkins.

Note

The following example configuration files set environment variables inside the Jenkinsfile_pipeline_gen file itself. Alternatively, you can set environment variables directly in Jenkins. You can configure global variables in the Jenkins system settings and node-specific variables in the node properties.

Set Environment Variables

In the node block of your copy of Jenkinsfile_pipeline_gen file, set the environment variables. When you specify a path, use either forward slashes or double-backslashes.

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 environment variable env.ARTIFACT_SERVICE_MODE to 'network'.

Environment Variable	Description
`env.PYTHON_ALIAS`	Alias for Python on the Jenkins agent.
`env.SUPPORT_PACKAGE_ROOT`	Root folder of support packages on the Jenkins agent. You can find installation directory by using the function `matlabshared.supportpkg.getSupportPackageRoot` in MATLAB on your Jenkins agent.
`env.ARTIFACT_SERVICE_MODE`	Artifact storage approach that you want to use, specified as either `'network'` or `'jfrog'`.
`env.NETWORK_STORAGE_PATH`	Path for storing artifacts on a network storage location when the `ARTIFACT_SERVICE_MODE` is set to `'network'`.
`env.PATH`	System path variable with the MATLAB bin folder of the Jenkins agent prepended. Adjusting the system path variable allows that specific MATLAB version to be available for the build. By default, the Jenkins pipeline generator options use the MATLAB plugin, which uses the topmost MATLAB version on the system path. For more information, see the Plugin Configuration Guide.

Example Configuration File for Network Artifact Store

For example, this version of the Jenkinsfile_pipeline_gen file specifies a network drive location on the C drive for the pipeline to store artifacts and identifies the paths to R2024b MATLAB and the support package on that machine.

// Copyright 2025 The MathWorks, Inc.
node{
    env.PYTHON_ALIAS = 'python3';
    env.SUPPORT_PACKAGE_ROOT = 'C:/ProgramData/MATLAB/SupportPackages/R2024b';

    env.ARTIFACT_SERVICE_MODE = 'network';         // 'jfrog'/'network'
    env.NETWORK_STORAGE_PATH = 'C:/Data/artifactManagement';
    // env.ARTIFACTORY_URL = 'http://localhost:8082/artifactory';
    // env.ARTIFACTORY_REPO_NAME = 'example-repo-local';
    // You need to set JFrog API token in Jenkins credentials with 'api_token_cred' id;
    // withCredentials([string( credentialsId: 'ARTIFACTORY_API_TOKEN_SECRET',variable: 'artifactory_api_token')]) {
    //     env.ARTIFACTORY_API_TOKEN = artifactory_api_token;
    // }
    
    env.PATH = "C:/Program Files/MATLAB/R2024b/bin;$PATH";
    cleanWs();scmVars=checkout scm;env.PADV_GIT_COMMIT=scmVars.GIT_COMMIT;

    stage('Pipeline Generation'){
        // Run generate_jenkins_pipeline.m file
        runMATLABCommand "addpath('$WORKSPACE');generate_jenkins_pipeline();"
        stash(includes:'scm/ir_dag.json, scm/simulink_pipeline', name:'ir_dag')
    }
    load "$WORKSPACE/scm/simulink_pipeline"
}

Using JFrog Artifactory

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

Change env.ARTIFACT_SERVICE_MODE to 'jfrog'.

Uncomment and set these environment variables.

Environment Variable	Description
`env.ARTIFACTORY_URL`	URL for the JFrog Artifactory server that manages the artifacts.
`env.ARTIFACTORY_REPO_NAME`	Name of the JFrog Artifactory repository where artifacts are stored.
`env.ARTIFACTORY_API_TOKEN`	API token for authenticating with JFrog Artifactory, retrieved from Jenkins credentials.

Uncomment the withCredentials code block that contains env.ARTIFACTORY_API_TOKEN.
Create an API token in JFrog and add the token to Jenkins credentials as a Secret text with the ID ARTIFACTORY_API_TOKEN_SECRET. See the JFrog documentation for Access Tokens and the Jenkins documentation for Using credentials.

JFrog Artifactory Versions

Example Configuration File for JFrog Artifactory

For example, this version of the Jenkinsfile_pipeline_gen file specifies a JFrog Artifactory repository for the pipeline to store artifacts.

// Copyright 2025 The MathWorks, Inc.
node{
    env.PYTHON_ALIAS = 'python3';
    env.SUPPORT_PACKAGE_ROOT = 'C:/ProgramData/MATLAB/SupportPackages/R2024b';

    env.ARTIFACT_SERVICE_MODE = 'jfrog';         // 'jfrog'/'network'
    // env.NETWORK_STORAGE_PATH = 'C:/Data/artifactManagement'; // only for 'network' artifact service mode
    env.ARTIFACTORY_URL = 'http://localhost:8082/artifactory';
    env.ARTIFACTORY_REPO_NAME = 'example-repo-local';
    // You need to set JFrog API token in Jenkins credentials with 'api_token_cred' id;
    withCredentials([string( credentialsId: 'ARTIFACTORY_API_TOKEN_SECRET',variable: 'artifactory_api_token')]) {
        env.ARTIFACTORY_API_TOKEN = artifactory_api_token;
    }
    
    env.PATH = "C:/Program Files/MATLAB/R2024b/bin;$PATH";
    cleanWs();scmVars=checkout scm;env.PADV_GIT_COMMIT=scmVars.GIT_COMMIT;

    stage('Pipeline Generation'){
        // Run generate_jenkins_pipeline.m file
        runMATLABCommand "addpath('$WORKSPACE');generate_jenkins_pipeline();"
        stash(includes:'scm/ir_dag.json, scm/simulink_pipeline', name:'ir_dag')
    }
    load "$WORKSPACE/scm/simulink_pipeline"
}

Update `generate_jenkins_pipeline.m` File

Edit the MATLAB function generate_jenkins_pipeline.m to set variables according to your Jenkins setup and to customize the pipeline generator options. The function opens your MATLAB project, stores pipeline generator options by using a padv.pipeline.JenkinsOptions object, and then generates a pipeline file by calling the pipeline generator function padv.pipeline.generatePipeline on that object. The Jenkins_pipeline_gen file loads the generated pipeline file, simulink_pipeline, to execute the tasks in your process.

Specify Required Pipeline Generator Options

In your copy of the MATLAB function, you must specify these pipeline generator options:

op.MatlabInstallationLocation — Path to bin folder for MATLAB installation on Jenkins agent
op.AgentLabel — Label for Jenkins agent

Example Function

For example, this generate_jenkins_pipeline.m file specifies an R2024b MATLAB installation and a Jenkins agent label of "jenkins-agent-label".

% Copyright 2025 The MathWorks, Inc.

function generate_jenkins_pipeline()
    cp = openProject(pwd);

    op = padv.pipeline.JenkinsOptions;
    op.PipelineArchitecture = "IndependentModelPipelines";
    op.GeneratorVersion = 2;
    op.GeneratedPipelineDirectory = fullfile(cp.RootFolder, "pipelines", "derived");
    op.MatlabInstallationLocation = "C:/Program Files/MATLAB/R2024b/bin";
    op.GeneratedPipelineDirectory = "scm";
    op.AgentLabel = "jenkins-agent-label";
    op.StopOnStageFailure = true;
    op.RunprocessCommandOptions.GenerateJUnitForProcess = true;
    op.ReportPath = "$PROJECTROOT$/PA_Results/Report/ProcessAdvisorReport";
    padv.pipeline.generatePipeline(op,"CIPipeline");
end

Customize Pipeline Generator Options

Optionally, you can customize other pipeline generator options by specifying the properties of the padv.pipeline.JenkinsOptions object in generate_jenkins_pipeline. For example, the template generate_jenkins_pipeline file specifies the pipeline architecture "IndependentModelPipelines" which creates parallel branches for running model tasks.

By default, the function generates a pipeline for the "CIPipeline" process. To target a different process, specify a different process name in the call to the padv.pipeline.generatePipeline function.

Update Process Model for Parallel Code Generation

The default pipeline architecture in the template generate_jenkins_pipeline file is "IndependentModelPipelines", which runs model tasks in parallel. 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.

In this example, because the generate_jenkins_pipeline file uses the parallel pipeline architecture, "IndependentModelPipelines", replace the example process model with the template process model that supports parallel code generation and analysis. In the MATLAB Command Window, enter:

createprocess(Template="parallel",Overwrite=true)

Configure Jenkins Pipeline Project to Use Template Files

To make your updated template files available to Jenkins, they must be in your project and source control system. Then, you configure your Jenkins Pipeline project to find and use the Jenkinsfile_pipeline_gen file in source control.

For the purpose of this example, commit and push your copy of the processAdvisorJenkinsExampleStart project to source control.
In Jenkins, in the Pipeline section of the project configuration window, select Pipeline script from SCM from the Definition list.
Select your source control system from the SCM list.
Paste your repository URL into the Repository URL box.

For more information, see the Jenkins documentation for Defining a Pipeline in SCM.

Generate and Inspect Pipeline

With the template files configured, a Jenkins pipeline generates the next time a build runs. If you integrated GitLab and Jenkins, new code commits or merge requests can automatically trigger a Jenkins build. Alternatively, you can manually run a Jenkins build to view the generated pipeline.

The typical generated pipeline includes these stages:

Pipeline Generation — This stage uses your Jenkins_pipeline_gen file to run MATLAB, execute your generate_jenkins_pipeline.m file, and load the generated pipeline file into Jenkins.
simulink_pipeline — This stage loads the generated pipeline file, simulink_pipeline, to execute the tasks in your process as stages of the Jenkins pipeline.

When the build finishes, the pipeline generator saves the task results, Process Advisor report, and the artifacts.dmr file for the digital thread into file named padv_artifacts.zip. You can access the file as a build artifact in Jenkins. By default, the template files also generate JUnit results which allow you to view and track task result outcomes as test results in Jenkins.