Integrate Process into Jenkins
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
Install Jenkins. See the Jenkins documentation for Installing Jenkins.
Install the following plugins for Jenkins:
MATLAB® Plugin for Jenkins. See MATLAB plugin on Jenkins Plugins Index.
Jenkins Core Plugin, which allows pipelines to archive artifacts using the
archiveArtifacts
step. See the Jenkins documentation forarchiveArtifacts
.JUnit Plugin, which allows Jenkins to show test failures and trends directly in the user interface. See JUnit plugin on Jenkins Plugins Index.
Job Cacher Plugin, which allows Jenkins to store caches. See Job Cacher plugin on Jenkins Plugins Index.
The pipeline generator requires the skipSave parameter that was introduced in plugin version
399.v12d4fa_dd3db_d
. Pipeline generation was tested using plugin version481.v15f51ca_4c6b_7
.
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.
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.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 aJenkinsfile
, you reconfigure the templateJenkinsfile
, 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.
Set up a remote GitLab repository by creating a new blank project. See the GitLab documentation for Create a project.
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 enteringcreateprocess(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.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.
In your MATLAB project, change your current folder to your project root and copy the template
Jenkinsfile
file into your project. The templateJenkinsfile
is generic and can work with any project.exampleJenkinsfile = fullfile(... matlabshared.supportpkg.getSupportPackageRoot,... "toolbox","padv","samples","Jenkinsfile_pipeline_gen"); copyfile(exampleJenkinsfile,"Jenkinsfile")
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 objectpadv.pipeline.JenkinsOptions
to specify the pipeline generation options.In the
Jenkinsfile
, update the file to specify the:Agent label for the Jenkins agent that you want to use within the
node(
block. For example:'labelName'
)//Scripted Pipeline node ('agent1') {
Git
branch
,credentialsId
, andurl
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. ThisJenkinsfile
acts as a parent pipeline file. The other sections of theJenkinsfile
use calls to theopenProject
andpadv.pipeline.generatePipeline
functions to open your project and generate a child pipeline file for your specific project and process. TheJenkinsfile
uses theload
command to load the generated child pipeline file.Add the
Jenkinsfile
to your project.Push the changes to your project to source control.
Configure your Jenkins project to use the
Jenkinsfile
in source control.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 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")));''' }
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.
Note
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.
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 inpadv.pipeline.JenkinsOptions
.The
Generate_PADV_Report
stage, which generates a Process Advisor build report.The stage,
Collect_Artifacts
, which collects build artifacts.
See Also
padv.pipeline.generatePipeline
| padv.pipeline.JenkinsOptions