padv.pipeline.JenkinsOptions

Options for generating pipeline configuration file for Jenkins

expand all in page

    Description

    Use the padv.pipeline.JenkinsOptions object to represent the desired options for generating a Jenkins® pipeline configuration file. To generate a Jenkins pipeline configuration file, use padv.pipeline.JenkinsOptions as an input argument to the padv.pipeline.generatePipeline function.

    There are two versions of the pipeline generator for Jenkins:

    Note

    Pipeline generator version 2 is recommended for enhanced file propagation and artifact management capabilities, but requires you to update your Jenkins setup and workflow.

    Creation

    Syntax

    options = padv.pipeline.JenkinsOptions(GeneratorVersion=1)
    options = padv.pipeline.JenkinsOptions(___,PropertyName=Value)
    options = padv.pipeline.JenkinsOptions(GeneratorVersion=2)
    options = padv.pipeline.JenkinsOptions(___,PropertyName=Value)

    Description

    Pipeline Generator Version 1

    options = padv.pipeline.JenkinsOptions(GeneratorVersion=1) returns configuration options for generating a Jenkins pipeline with pipeline generator version 1.

    Version 1 uses the original pipeline generator functionality. For more information, see Integrate Process into Jenkins.

    example

    options = padv.pipeline.JenkinsOptions(___,PropertyName=Value) sets properties using one or more name-value arguments.

    Pipeline generator version 2 is recommended for enhanced file propagation and artifact management capabilities, but requires you to update your Jenkins setup and workflow.

    Pipeline Generator Version 2

    options = padv.pipeline.JenkinsOptions(GeneratorVersion=2) returns configuration options for generating a Jenkins pipeline with pipeline generator version 2.

    Version 2 includes enhanced features like external artifact management with JFrog Artifactory but requires a different setup than version 1. For more information, see Enhanced Process Integration and Artifact Management for Jenkins.

    example

    options = padv.pipeline.JenkinsOptions(___,PropertyName=Value) sets properties using one or more name-value arguments.

    Note that pipeline generator version 2 ignores the properties ShellEnvironment, EnablePipelineCaching, and UseSameExecutorForSequentialStages.

    Properties

    expand all

    Jenkins agent that executes pipeline, specified as a string or string array.

    Pipeline Generator Version 1 ignores this property if the UseSameExecutorForSequentialStages property is true.

    Example: "high_memory"

    Data Types: string

    When to collect build artifacts, specified as:

    • "never", 0, or false — Never collect artifacts

    • "on_success" — Only collect artifacts when the pipeline succeeds

    • "on_failure" — Only collect artifacts when the pipeline fails

    • "always", 1, or true — Always collect artifacts

    Example: "on_failure"

    Data Types: logical | string

    Name of ZIP file for job artifacts, specified as a string.

    Example: "my_job_artifacts.zip"

    Data Types: string

    File name of generated Jenkins pipeline file, specified as a string.

    By default, the generated pipeline file generates into the subfolder derived > pipeline, relative to the project root. To change where the pipeline file generates, specify GeneratedPipelineDirectory.

    Example: "padv_generated_pipeline_file"

    Data Types: string

    Specify whether Jenkins uses MATLAB Plugin to launch MATLAB, specified as a numeric or logical 0 (false) or 1 (true).

    If the property UseMatlabPlugin is true, Jenkins uses the "runMATLABCommand" step to launch MATLAB and the pipeline generator ignores the properties MatlabLaunchCmd and MatlabStartupOptions. For more information, see runMATLABCommand.

    • For Pipeline Generator Version 1, if the property UseMatlabPlugin is false, the Jenkins pipeline uses the specified ShellEnvironment to launch MATLAB and uses the options specified by the properties MatlabLaunchCmd and MatlabStartupOptions.

    • For Pipeline Generator Version 2, if the property UseMatlabPlugin is false, the pipeline generator ignores the ShellEnvironment property. If the agent is a UNIX® machine, the Jenkins pipeline uses a shell script. If the agent is not a UNIX machine, the Jenkins pipeline uses a Windows® batch script.

    Using the MATLAB Plugin for Jenkins is recommended. For more information, see the MATLAB plugin for Jenkins.

    Data Types: logical

    Shell environment Jenkins uses to launch MATLAB, specified as one of these values:

    • "bat" — Windows batch script

    • "sh" — Shell script

    • "pwsh" — PowerShell Core script

    • "powershell" — Windows PowerShell script

    • "" — Automatically use "bat" or "sh" based on the platform where pipeline generation runs

    Pipeline Generator Version 2 ignores this property and instead:

    • If the agent is a UNIX machine, the Jenkins pipeline uses a shell script.

    • If the agent is not a UNIX machine, the Jenkins pipeline uses a Windows batch script.

    Data Types: string

    Use the same executor for sequential stages, specified as either a numeric or logical:

    • true (1) — By default, Pipeline Generator Version 1 configures sequential stages to use the same executor, minimizing executor usage and maintaining a shared workspace. When generating a Jenkins pipeline from a parent Jenkinsfile, the sequential stages use the same executor that you defined in the top-level node('labelName') block of the parent Jenkinsfile and ignore the AgentLabel property. For more information, see Integrate Process into Jenkins.

    • false (0) — Pipeline Generator Version 1 configures the pipeline to allow Jenkins to release the current agent and potentially use different agents for subsequent stages. This approach can lead to smaller, more manageable jobs, but can require additional pipeline execution time. Since different agents can use different workspaces, Pipeline Generator Version 1 stores the outputs from each stage and passes those outputs to the subsequent stages. For more information on sequential stages, see the Jenkins documentation for Sequential Stages.

    Pipeline Generator Version 2 ignores this property.

    Data Types: logical

    Options for runprocess command, specified as a padv.pipeline.RunProcessOptions object.

    The object padv.pipeline.RunProcessOptions has properties for each of the name-value arguments in the runprocess function, except for the Scope arguments Tasks, Process, Subprocesses, and FilterArtifact.

    Note

    GenerateJUnitForProcess is set to false by default in padv.pipeline.RunProcessOptions. Previously, this property was true by default.

    The GenerateJUnitForProcess property in padv.pipeline.JenkinsOptions will be removed in a future release. Make sure to specify the GenerateJUnitForProcess property in padv.pipeline.RunProcessOptions to the value that you want the pipeline to use.

    Example: padv.pipeline.RunProcessOptions()

    Number of stages and grouping of tasks in CI pipeline, specified as one of the pipeline architectures in the table.

    Pipeline ArchitectureDescription
    padv.pipeline.Architecture.SingleStage

    The pipeline has a single stage, named Runprocess, that runs each of the tasks in the process.

    Example pipeline graphic that shows one stage that runs all tasks on all models

    padv.pipeline.Architecture.SerialStages

    The pipeline has one stage for each task iteration in the process.

    Example pipeline graphic that shows one stage that runs TaskA on ModelA, one stage that runs TaskA on ModelB, one stage that runs TaskB on ModelA, and one stage that runs TaskB on ModelB

    padv.pipeline.Architecture.SerialStagesGroupPerTask

    The pipeline has one stage for each task in the process.

    Example pipeline graphic that shows one stage that runs one task, TaskA, and one stage that runs another task, TaskB

    padv.pipeline.Architecture.IndependentModelPipelines

    The pipeline contains parallel, downstream pipelines or branches for each model. Each downstream pipeline or branch independently runs the tasks associated with that model.

    To make sure the jobs run in parallel, make sure that you either:

    • Have multiple agents available

    • Configure your agent to run multiple jobs concurrently

    Example pipeline graphic showing two parallel downstream pipelines. One pipeline that runs TaskA and TaskB on ModelA. One pipeline that runs TaskA and TaskB on ModelB.

    Note

    You must have at least two Jenkins executors available. The pipeline generator requires one executor to generate the pipeline and load the children stages and at least one other 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 defining Jenkins executors, see the Jenkins documentation for Managing Nodes.

    For Pipeline Generator Version 1, if you choose a pipeline architecture other than SingleStage, the pipeline generator can create complex Jenkinsfile files that exceed size limits. If Jenkins generates the error Method too large, consider simplifying the pipeline architecture to use the SingleStage architecture instead or upgrade to Pipeline Generator Version 2 as shown in Enhanced Process Integration and Artifact Management for Jenkins.

    For Pipeline Generator Version 2, 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.

    Pipeline Generator Version 2 does not support using the built-in query padv.builtin.query.FindComponents when the pipeline architecture is padv.pipeline.Architecture.IndependentModelPipelines. You can use a different query, like padv.builtin.query.FindModelsWithLabel, or use a different pipeline architecture instead.

    Example: padv.pipeline.Architecture.IndependentModelPipelines

    Example: "IndependentModelPipelines"

    Command to start MATLAB program, specified as a string.

    If you use a custom command to launch MATLAB on your machine, make sure to set this property. The default value of this property is "matlab", which assumes MATLAB is available in the PATH environment variable for your system and runs the default MATLAB executable.

    The pipeline generator ignores this property when UseMatlabPlugin is true.

    Example: "C:\Program Files\MATLAB\R2024b\bin\matlab.exe"

    Data Types: string

    Command-line startup options for MATLAB, specified as a string.

    Use this property to specify the command-line startup options that the generated pipeline file uses when starting the MATLAB program. By default, the pipeline generator launches MATLAB using the -batch option. If you need to run MATLAB without the -batch option, specify the property AddBatchStartupOption as false.

    Some MATLAB code, including some built-in tasks, can only run successfully if a display is available for your machine. For more information and a list of built-in tasks that require a display, see Set Up Virtual Display Machines Without Displays.

    The pipeline generator ignores this property when UseMatlabPlugin is true.

    Example: "-nodesktop -logfile mylogfile.log"

    Data Types: string

    Specify whether to open MATLAB using -batch startup option, specified as a numeric or logical 0 (false) or 1 (true).

    If you need to launch MATLAB with options that are not compatible with -batch, specify AddBatchStartupOption as false.

    Data Types: logical

    Location where the generated pipeline file generates, specified as a string.

    By default, the generated pipeline file is named "simulink_pipeline". To change the name of the generated pipeline file, specify the GeneratedJenkinsFileName property.

    Example: fullfile("derived","pipeline","test")

    Data Types: string

    Generate Process Advisor build report, specified as a numeric or logical 1 (true) or 0 (false).

    Data Types: logical

    File format for the generated report, specified as one of these values:

    • "pdf" — PDF file

    • "html" — HTML report, packaged as a zipped file that contains the HTML file, images, style sheet, and JavaScript® files of the report

    • "html-file" — HTML report, consisting of a single HTML file that contains the text, style sheets, JavaScript, and base64-encoded images of the report

    • "docx" — Microsoft® Word document

    Name and path of generated report, specified as a string array.

    As a recommended practice, set the ReportPath to a sub-folder within the project root. CI pipelines cannot archive files located in the project root itself.

    Example: "$PROJECTROOT$/PA_Results/Report/ProcessAdvisorReport"

    Data Types: string

    Stop running pipeline after stage fails, specified as a numeric or logical 0 (false) or 1 (true).

    By default, the pipeline continues to run, even if a stage in the pipeline fails.

    Data Types: logical

    Check for outdated results after merge, specified as a numeric or logical 1 (true) or 0 (false).

    Generator Version 1 no longer merges artifact databases and therefore ignores this property.

    Generator Version 2 uses this property. When specified as true, the pipeline checks if task results are still up-to-date after merging artifact database files from parallel jobs and generates a warning. A successful merge should not produce outdated results. If there are outdated results, there could be an issue with the merge.

    Data Types: logical

    Enable pipeline caching to support incremental builds in CI, specified as a numeric or logical 0 (false) or 1 (true).

    For Pipeline Generator Version 1, generated pipelines use caching by default to help the performance of incremental builds in CI. However, if a generated pipeline has persistent conflicts and generates errors when merging artifact information from parallel jobs, you can disable pipeline caching by specifying EnablePipelineCaching as 0 (false). Disabling pipeline caching increases build times, but can help avoid merge conflicts.

    Pipeline Generator Version 2 ignores this property.

    Data Types: logical

    Examples

    collapse all

    This example shows how to use the pipeline generator API in isolation, but typically you use these commands inside your Jenkinsfile or generate_jenkins_pipeline.m file. When you generate a Jenkins pipeline, you provide a JenkinsOptions object that specifies various configuration settings like the MATLAB installation location, pipeline architecture, and Jenkins agent labels. The pipeline generator applies these options to generate a pipeline for your specific project and process.

    Load a project. For this example, you can load a Process Advisor example project.

    processAdvisorExampleStart

    Store your Jenkins pipeline generation options by creating a padv.pipeline.JenkinsOptions object. This object allows you to set various properties that determine how the Jenkins pipeline generates.

    op = padv.pipeline.JenkinsOptions;

    To have the generated pipeline use separate stages for each task iteration, set the PipelineArchitecture property in the options object to "SerialStages".

    op.PipelineArchitecture = "SerialStages";

    For Pipeline Generator Version 1, you set the GeneratorVersion property to 1 and typically specify these options in the runMATLABCommand inside your Jenkinsfile as shown in Integrate Process into Jenkins.

    // Scripted Pipeline
node('#### Enter your agent label ####') {

    stage('Git_Clone') {
        git branch: '#### Enter your branch ####',
            credentialsId: '#### Enter your credentials, if any ####',
            url: '#### Enter your repository URL ####'
    }

    // Requires MATLAB plugin
    stage('Pipeline Generation') {

        env.PATH = "C:\\Program Files\\MATLAB\\R2024a\\bin;${env.PATH}"

        /* Open the project and generate the pipeline using
           appropriate options */

        runMATLABCommand '''cp = openProject(pwd);
        padv.pipeline.generatePipeline(...
        padv.pipeline.JenkinsOptions(...
        PipelineArchitecture = padv.pipeline.Architecture.SerialStagesGroupPerTask,...
        GeneratorVersion = 1, ...
        GeneratedJenkinsFileName = "simulink_pipeline",...
        GeneratedPipelineDirectory = fullfile("derived","pipeline")));'''
    }

    // Pass necessary environment variables to generated pipeline
    withEnv(["PATH=C:\\Program Files\\MATLAB\\R2024a\\bin;${env.PATH}"]) {

        def rootDir = pwd()

        /* This file is generated automatically by 
           padv.pipeline.generatePipeline with a default name 
           of simulink_pipeline. Update this field if the 
           name or location of the generated pipeline file is changed */

        load "${rootDir}/derived/pipeline/simulink_pipeline"
    }
}

    For Pipeline Generator Version 2, you set the GeneratorVersion property to 2 and specify these options inside the MATLAB function generate_jenkins_pipeline.m as shown in Enhanced Process Integration and Artifact Management for Jenkins.

    % 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

    The template Jenkinsfile file runs MATLAB, calls generate_jenkins_pipeline(), and loads the generated pipeline file into Jenkins.

    // 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"
}
    For more information, see Enhanced Process Integration and Artifact Management for Jenkins.

    Version History

    expand all

    See Also

    Topics

    External Websites