padv.pipeline.GitHubOptions
Options for generating pipeline configuration file for GitHub
Description
Use the padv.pipeline.GitHubOptions
object to represent the
desired options for generating a GitHub® pipeline configuration file. To generate a GitHub pipeline configuration file, use padv.pipeline.GitHubOptions
as
an input argument to the padv.pipeline.generatePipeline
function. For
information on how to use the pipeline generator to integrate into a GitHub CI system, see Integrate Process into GitHub.
Creation
Description
returns configuration options for generating a GitHub pipeline configuration file.options
= padv.pipeline.GitHubOptions
This functionality requires CI/CD Automation for Simulink Check.
sets properties using one or more name-value arguments. For example,
options
= padv.pipeline.GitHubOptions(Name=Value
)padv.pipeline.GitHubOptions(RunnerLabels="Linux")
creates an options
object that specifies that a generated pipeline configuration file use
Linux
as the GitHub Action runner label.
Properties
RunnerLabels
— GitHub runner labels
"self-hosted"
(default) | string
GitHub runner labels, specified as a string.
The labels determine which GitHub runner can execute the job. For more information, see https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job#targeting-runners-in-a-group.
Example:
padv.pipeline.GitHubOptions(RunnerLabels = "Linux")
Data Types: string
ArtifactZipFileName
— Name of ZIP file for job artifacts
"padv_artifacts.zip"
(default) | string
Name of ZIP file for job artifacts, specified as a string.
Example: padv.pipeline.GitHubOptions(ArtifactZipFileName =
"my_job_artifacts.zip")
Data Types: string
RetentionDays
— How many days GitHub stores workflow artifacts
"30"
(default) | string
How many days GitHub stores workflow artifacts, specified as a string. This property
corresponds to the job keyword "retention-days"
in GitHub. After the specified number of retention days, the artifacts expire and
GitHub deletes the artifacts.
Example: padv.pipeline.GitHubOptions(RetentionDays =
"90")
Data Types: string
GeneratedYMLFileName
— File name of generated GitLab® pipeline file
"simulink_pipeline"
(default) | string
File name of generated GitLab pipeline file, specified as a string.
By default, the generated pipeline generates into the subfolder derived > pipeline, relative to the project root. To change where the pipeline file
generates, specify GeneratedPipelineDirectory
.
Example: padv.pipeline.GitHubOptions(GeneratedYMLFileName =
"padv_generated_pipeline_file")
Data Types: string
MatlabInstallationLocation
— Path to MATLAB® installation location
"PATH_TO_MATLAB"
(default) | string
Path to MATLAB installation location, specified as a string.
Make sure the path that you specify uses the MATLAB root folder location and file separators for the operating system of your GitHub runner.
Example:
"C:\Program Files\MATLAB\R2023a\bin"
Example:
"/usr/local/MATLAB/R2023a/bin"
Example:
"/Applications/MATLAB_R2023a.app/bin"
Data Types: string
EnableArtifactCollection
— When to collect build artifacts
"always"
, 1
, or
true
(default) | "never"
, 0
, or
false
| "on_success"
| "on_failure"
When to collect build artifacts, specified as:
"never"
,0
, orfalse
— Never collect artifacts"on_success"
— Only collect artifacts when the pipeline succeeds"on_failure"
— Only collect artifacts when the pipeline fails"always"
,1
, ortrue
— Always collect artifacts
If the pipeline collects artifacts, the child pipeline contains a job,
Collect_Artifacts
, that compresses the build artifacts into a ZIP
file and attaches the file to the job.
Example: padv.pipeline.GitHubOptions(EnableArtifactCollection=false)
Data Types: logical
| string
ShellEnvironment
— Shell environment GitHub uses to launch MATLAB
"bash"
(default) | "pwsh"
Shell environment GitHub uses to launch MATLAB, specified as one of these values:
"bash"
— UNIX® shell script"pwsh"
— PowerShell Core script
Example: padv.pipeline.GitHubOptions(ShellEnvironment =
"pwsh")
Data Types: string
CheckoutSubmodules
— Checkout Git™ submodules
"false"
(default) | "true"
| "recursive"
Checkout Git submodules at the beginning of each pipeline stage, specified as either:
"false"
"true"
"recursive"
This property uses the GitHub Action checkout@v3
. For information about the submodule
input values, see https://github.com/marketplace/actions/checkout-submodules.
Example: padv.pipeline.GitHubOptions(CheckoutSubmodules =
"true")
Data Types: string
RunprocessCommandOptions
— Options for runprocess
command
padv.pipeline.RunProcessOptions
(default) | padv.pipeline.RunProcessOptions
object
Options for runprocess
command, specified as a
padv.pipeline.RunProcessOptions
object.
padv.pipeline.RunProcessOptions
has properties for the name-value
arguments in the runprocess
function, except for the arguments Tasks
,
Process
, Subprocesses
, and
FilterArtifact
.
For example, to have the pipeline generator use a command like
runprocess(DryRun = true)
in GitHub, you can create a padv.pipeline.RunProcessOptions
object,
specify the property values, and pass the object to
padv.pipeline.GitHubOptions
:
rpo = padv.pipeline.RunProcessOptions; rpo.DryRun = true; gho = padv.pipeline.GitHubOptions(RunprocessCommandOptions = rpo);
Note
The GenerateJUnitForProcess
property in
padv.pipeline.RunProcessOptions
is set to
false
by default. Previously, in
padv.pipeline.GitHubOptions
, this property was
true
by default. The
GenerateJUnitForProcess
property in
padv.pipeline.GitHubOptions
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
PipelineArchitecture
— Number of stages and grouping of tasks in CI pipeline
padv.pipeline.Architecture.SingleStage
(default) | padv.pipeline.Architecture.SerialStages
| padv.pipeline.Architecture.SerialStagesGroupPerTask
| padv.pipeline.Architecture.IndependentModelPipelines
Number of stages and grouping of tasks in CI pipeline, specified as either:
padv.pipeline.Architecture.SingleStage
— The pipeline has a single stage, named Runprocess, that runs each of the tasks in the process.padv.pipeline.Architecture.SerialStages
— The pipeline has one stage for each task iteration in the process.padv.pipeline.Architecture.SerialStagesGroupPerTask
— The pipeline has one stage for each task in the process.padv.pipeline.Architecture.IndependentModelPipelines
— The pipeline contains parallel, downstream pipelines for each model. Each downstream pipeline 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: padv.pipeline.GitHubOptions(PipelineArchitecture =
padv.pipeline.Architecture.SerialStages)
MatlabLaunchCmd
— Command to start MATLAB program
"matlab"
(default) | string
Command to start MATLAB program, specified as a string.
Use this property to specify how the pipeline starts the MATLAB program. This property defines how the script in the generated pipeline file launches MATLAB.
Example: padv.pipeline.GitHubOptions(MatlabLaunchCmd =
"matlab")
Data Types: string
MatlabStartupOptions
— Command-line startup options for MATLAB
"-nodesktop -logfile output.log"
(default) | string
Command-line startup options for MATLAB, specified as a string.
Use this property to specify the command-line startup options that the pipeline uses
when starting the MATLAB program. This property defines the command-line startup options that
appear next to the -batch
option and
MatlabLaunchCmd
value in the"script"
section
of the generated pipeline file. The pipeline starts MATLAB with the specified startup options.
By default, the support package launches MATLAB using the -batch
option. If you need to run MATLAB without the -batch
option, specify the property
AddBatchStartupOption
as false.
Note
If you run MATLAB using the -nodisplay
option or you use a machine that
does not have a display (like many CI runners and Docker® containers), you should set up a virtual display server before you
include the following built-in tasks in your process model:
Generate SDD Report
Generate Simulink Web View
Generate Model Comparison
For information, see Set Up Virtual Display Machines Without Displays.
Example: padv.pipeline.GitHubOptions(MatlabStartupOptions = "-nodesktop
-logfile mylogfile.log")
Data Types: string
AddBatchStartupOption
— Specify whether to open MATLAB using -batch
startup option
1
(true
) (default) | 0
(false
)
Specify whether to open MATLAB using -batch
startup option, specified as a numeric or
logical 0
(false
) or 1
(true
).
By default, the support package launches MATLAB in CI using the -batch
startup option.
If you need to launch MATLAB with options that are not compatible with -batch
,
specify AddBatchStartupOption
as false
.
Example: padv.pipeline.GitHubOptions(AddBatchStartupOption =
false)
Data Types: logical
GeneratedPipelineDirectory
— Specify where the generated pipeline file generates
fullfile("derived","pipeline")
(default) | string
Specify where the generated pipeline file generates, specified as a string.
This property defines the directory where the generated pipeline file generates.
By default, the generated pipeline file is named
"simulink_pipeline.yml"
. To change the name of the generated
pipeline file, specify GeneratedYMLFileName
.
Example: padv.pipeline.GitHubOptions(GeneratedPipelineDirectory =
fullfile("derived","pipeline","test"))
Data Types: string
GenerateReport
— Generate Process Advisor build report
true
or 1
(default) | false
or 0
Generate Process Advisor build report, specified as a numeric or logical
1
(true
) or 0
(false
).
Example: padv.pipeline.GitHubOptions(GenerateReport =
false)
Data Types: logical
ReportFormat
— File format for generated report
"pdf"
(default) | "html"
| "html-file"
| "docx"
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"docx"
— Microsoft® Word document
Example: padv.pipeline.GitHubOptions(ReportFormat =
"html-file")
ReportPath
— Name and path of generated report
"ProcessAdvisorReport"
(default) | string array
Name and path of generated report, specified as a string array.
By default, the report path uses a relative path to the project root and the
pipeline generator generates a report
ProcessAdvisorReport.pdf
.
Example: padv.pipeline.GitHubOptions(ReportPath =
"myReport")
Data Types: string
StopOnStageFailure
— Stop running pipeline after stage fails
0
(false
) (default) | 1
(true
)
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.
Example: padv.pipeline.GitHubOptions(StopOnStageFailure =
true)
Data Types: logical
CheckOutdatedResultsAfterMerge
— Check for outdated results after merge
1
(true
) (default) | 0
(false
)
Check for outdated results after merge, specified as a numeric or logical
1
(true
) or 0
(false
).
The pipeline generator no longer uses this property.
Example: false
Data Types: logical
EnablePipelineCaching
— Enable pipeline caching to support incremental builds in CI
1
(true
) (default) | 0
(false
)
Enable pipeline caching to support incremental builds in CI, specified as a numeric
or logical 0
(false
) or 1
(true
).
By default, generated pipelines use caching to help the performance of incremental
builds in CI. However, if a generated pipeline 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.
Example: false
Data Types: logical
Examples
Specify GitHub Configuration Options When Generating Pipeline Configuration File
Create a padv.pipeline.GitHubOptions
object and
change the options. When you generate a pipeline configuration file, the file uses the
specified options.
This example shows how to use the pipeline generator API. For information on how to use the pipeline generator to integrate into a GitHub CI system, see Integrate Process into GitHub.
Load a project. For this example, you can load a Process Advisor example project. In the MATLAB Command Window, enter:
processAdvisorExampleStart
Specify your GitHub pipeline configuration options by creating a
padv.pipeline.GitHubOptions
object and modifying the object
properties. For example, if you have a GitHub runner that uses a MATLAB installation at
/opt/matlab/r2023a
:
GitHubOptions = padv.pipeline.GitHubOptions
GitHubOptions.MatlabInstallationLocation = "/opt/matlab/r2023a";
Generate a GitHub pipeline configuration file by using the function
padv.pipeline.generatePipeline
with the specified options.
padv.pipeline.generatePipeline(GitHubOptions);
Note
Calling padv.pipeline.generatePipeline(GitHubOptions)
is
equivalent to calling
padv.pipeline.generateGitHubPipeline(GitHubOptions)
.
By default, the generated pipeline configuration file is named
simulink_pipeline.yml
and is located under the project root, in the
subfolder derived > pipeline.
The GeneratedYMLFileName
and
GeneratedPipelineDirectory
properties of the
padv.pipeline.GitHubOptions
object control the name and location of
the generated pipeline configuration file.
For information on how to use the pipeline generator to integrate into a GitHub CI system, see Integrate Process into GitHub.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)