padv.pipeline.GitHubOptions

Options for generating pipeline configuration file for GitHub

expand all in page

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.

There are two versions of the pipeline generator for GitHub:

Note

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

Creation

Syntax

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

Description

Pipeline Generator Version 1

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

example

options = padv.pipeline.GitHubOptions(___,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 GitHub setup and workflow.

Pipeline Generator Version 2

options = padv.pipeline.GitHubOptions(GeneratorVersion=2) returns configuration options for generating a GitHub 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 GitHub.

example

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

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

Properties

expand all

GitHub runner labels, specified as a string.

The labels determine which GitHub runner can execute the job. For more information, see the GitHub documentation for Choosing the runner for a job.

Example: "Linux"

Data Types: string

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

Example: "my_job_artifacts.zip"

Data Types: 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. For more information, see the GitHub documentation for Configuring a custom artifact retention period.

Pipeline Generator Version 2 ignores this property and instead uses the default organization retention policy. For more information, see the GitHub documentation for Artifact and log retention policy.

Example: RetentionDays = "90"

Data Types: string

File name of generated GitLab 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

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

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

Data Types: logical | string

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

  • "bash" — UNIX® shell script

  • "pwsh" — PowerShell Core script

Pipeline Generator Version 2 ignores this property and instead:

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

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

Data Types: string

Checkout Git submodules at the beginning of each pipeline stage, specified as either:

  • "false"

  • "true"

  • "recursive"

This property uses the GitHub Action checkout@v4. For information about the submodule input values, see the GitHub documentation for Checkout submodules.

Data Types: string

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.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()

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

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.

Note

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.

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.

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.

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 the GeneratedYMLFileName 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.

By default, the report path uses a relative path to the project root and the pipeline generator generates a report ProcessAdvisorReport.pdf.

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

When you generate a GitHub Actions pipeline file, you provide a GitHubOptions object that specifies various configuration settings like the MATLAB installation location, pipeline architecture, and GitHub 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

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/r2024b:

GitHubOptions = padv.pipeline.GitHubOptions
GitHubOptions.MatlabInstallationLocation = "/opt/matlab/r2024b";

Set the GeneratorVersion property to specify the pipeline generator version that you want to use.

  • For Pipeline Generator Version 1, set the property to 1.

    GitHubOptions.GeneratorVersion = 1;

  • For Pipeline Generator Version 2, set the property to 2.

    GitHubOptions.GeneratorVersion = 2;

Generate GitHub pipeline configuration files by using the function padv.pipeline.generatePipeline with the specified options.

padv.pipeline.generatePipeline(GitHubOptions);

Update your GitHub Actions Workflow.

Version History

expand all

See Also

Topics

External Websites