Process Integration and Artifact Management for GitLab

Since R2023b. Recommended over Integrate Process into GitLab.

This example uses:

You can set up continuous integration (CI) for your model-based design projects in GitLab® by using the CI Support Package for Simulink. The support package allows you to generate pipeline files that run pipelines of tasks in GitLab and manage artifacts by using network storage, JFrog Artifactory, Amazon S3™, or Azure® Blob storage.

This example shows how to:

  1. Set up a GitLab project and GitHub® runner for running processes.

  2. Define tasks for your project by using an example process model.

  3. Connect your MATLAB® project to a remote GitLab repository for source control integration.

  4. Perform a one-time setup of GitLab template files that enable you to automatically generate a GitLab CI pipeline for your specific process model and pipeline settings.

  5. Push changes to source control and inspect the automatically generated pipeline.

This example shows the recommended way to integrate your process into GitLab by using pipeline generator version 2. For alternatives, see Approaches to Running Processes in CI.

Set Up GitLab Project and Runner

Set up a source-controlled remote repository where you store your project and a build agent that can run your pipeline on that repository. Typically, the build agent is a self-hosted build agent rather than a cloud-hosted build agent. For this example, you can use GitLab as both your remote repository and CI system, and then create a self-hosted GitLab Runner to run your pipelines.

  1. In GitLab, set up a remote repository by creating a new blank project. See the GitLab documentation for Create a project.

  2. Install, register, and start a GitLab Runner on a machine. The GitLab Runner application allows a machine to act as a build agent in GitLab. If you assign a tag to your Runner, make a note of the tag name. See the GitLab documentation for Install GitLab Runner.

  3. Install the required products and tools on your build agent by using one of these approaches:

    • Option 1: Manually Install Products and Tools on Build Agent

      1. Install MATLAB, Simulink®, Simulink Check™, the CI Support Package for Simulink, and any other products that your process requires. For more information, see Tips for Setting Up CI Agents.

      2. Install Python® with the alias python3 available in your system path. The pipeline generator was developed with Python 3.11. Optionally, to add colors to CI job logs, you can also install the Python library colorlog.

      3. By default, the pipeline generator assumes that you have a shared network storage location for artifacts. However, if you plan to use an external artifact management system instead, make sure to install the CLI tool for your chosen system:

    • Option 2: Use Prebuilt Docker® Image

      You can simplify and automate build agent setup by using a prebuilt Docker image as your build environment. You can create a Docker image for pipeline generation by following the steps in Build and Use Docker Image to Run Processes. The image includes the CI support package, Python, artifact management CLIs, and other CI tools for pipeline generation.

Before you continue, make sure MATLAB is available on the system PATH so the build agent can access MATLAB.

Connect MATLAB Project to GitLab

Connect your MATLAB project to your remote repository so that you can push your changes to the remote GitLab repository and allow GitLab to automate a CI pipeline for the project.

  1. For this example, create a copy of the Process Advisor example project for GitLab in MATLAB.

    processAdvisorGitLabExampleStart
    This example project contains:

    • A process model, processmodel.m, that defines a process with common model-based design tasks. For information on how to customize a template process model for your development and verification workflow, see Customize Your Process Model.

    • Two template files, .gitlab-ci.yml and generate_gitlab_pipeline.m, for automatically generating pipelines.

  2. Connect your project, remote repository, and CI platform by adding the remote URL to your local repository. For more information, see Share Git Repository to Remote. Typically, a remote URL has the format https://gitlab.com/gitlab-org/gitlab.git.

    The example project is already set up to use local Git™ source control. For information on how to use source control with your projects, see Use Source Control with MATLAB Projects.

Add Template Files to Project

The example project, processAdvisorGitLabExampleStart, contains the required template files for setting up pipeline generation:

  • .gitlab-ci.yml — GitLab pipeline file that automates the generation and execution of the pipeline for your process and process model.

  • generate_gitlab_pipeline.m — MATLAB file that configures pipeline generator options, such as the pipeline architecture and GitLab Runner labels, and generates a CI pipeline file and supporting files.

If you are using a different project, you must copy and add these files into your project.

Update .gitlab-ci.yml File

Edit the .gitlab-ci.yml file to set the variables according to your GitLab setup.

  1. Specify the following environment variables in your .gitlab-ci.yml file, as needed, for your pipeline setup.

    Variable NameRequired/OptionalDescriptionExample Value
    MW_SUPPORT_PACKAGE_ROOT

    Required

    Path to the MATLAB support package root on your build agent.

    You can get the path by running matlabshared.supportpkg.getSupportPackageRoot on the agent.

    		"C:\\ProgramData\\MATLAB\\SupportPackages\\R2025a\\bin"
    MW_RELATIVE_PROJECT_PATH

    Optional

    Relative path to your project if it is in a subfolder of the repository root.

    The path must end with /.

    For more information, see RelativeProjectPath.

    		"src/myproject/"
    MW_REMOTE_BUILD_CACHE_NAME

    Optional

    Name of remote build cache directory where the pipeline generator stores pipeline artifact caches on the remote build cache service.

    By default, the name of your CI pipeline.

    As a best practice, use a unique name for each pipeline and project to avoid conflicts between different pipelines.

    For more information, see RemoteBuildCacheName.

    		"My MATLAB Pipeline"
    MW_PIPELINE_GEN_DIRECTORY

    Optional

    Directory for generated pipeline files.

    By default, _pipelineGen_.

    		_padvPipelineGen_

    Note

    When you specify a path, use either forward slashes or double-backslashes.

  2. Specify which GitLab runners can run the pipeline by replacing <GitLab runner tags> with the tags for your GitLab runners. For example:

    tags: ["my_gitlab_runner"]

Update generate_gitlab_pipeline.m File

Edit the MATLAB function generate_gitlab_pipeline.m to set variables according to your GitLab setup and to customize the pipeline generator options. The function opens your MATLAB project, specifies pipeline generator options by using a padv.pipeline.GitLabOptions object, and then generates a pipeline file and supporting files by calling the pipeline generator function padv.pipeline.generatePipeline on that object.

  1. Specify which GitLab runners can run the pipeline by replacing <GitLab runner tags> with the tags for your GitLab runners. For example:

    op.Tags = "my_gitlab_runner";

  2. Choose where to store your artifacts by setting the ArtifactServiceMode property. Each artifact storage approach has its own specific configuration requirements as shown in ArtifactServiceMode. Depending on which artifact storage approach you choose, you need to specify additional properties and GitLab CI/CD variables.

    Artifact Storage ApproachExample CodeRequired GitLab CI/CD Variables

    Network storage

    op.ArtifactServiceMode = "network";
op.NetworkStoragePath = "/artifactManagement/cacheStorage";

    None.

    JFrog Artifactory

    op.ArtifactServiceMode = "jfrog";
op.ArtifactoryUrl = "http://localhost:8082/artifactory";
op.ArtifactoryRepoName = "example-repo-local";

    Store the JFrog API token as a secret named ARTIFACTORY_API_TOKEN_SECRET in GitLab.

    Amazon S3

    op.ArtifactServiceMode = "s3";
op.S3BucketName = "my-artifacts-bucket";
op.S3AwsAccessKeyID = "AKIAIOSFODNN7EXAMPLE";

    Store the Amazon S3 access key as a secret named S3_AWS_SECRET_ACCESS_KEY_SECRET in GitLab.

    Azure Blob

    op.ArtifactServiceMode = "azure_blob";
op.AzContainerName = "mycontainer";

    Store the Azure storage account connection string as a secret named AZ_CONNECTION_STRING_SECRET in GitLab.

  3. Optionally, if you want to runs tasks inside a containerized environment, such as a Docker container, uncomment and specify the properties RunnerType and ImageTag. For example:

    op.RunnerType = "container";
op.ImageTag = 'my-docker-image-name';
    Depending on your setup, you might need to make adjustments to the MatlabLaunchCmd, MatlabStartupOptions, AddBatchStartupOption properties. For example:
    % Docker image settings
op.MatlabLaunchCmd = "xvfb-run -a matlab -batch"; 
op.MatlabStartupOptions = "";
op.AddBatchStartupOption = false;

You can customize other pipeline generator options by specifying the other properties of the padv.pipeline.GitLabOptions object in the generate_gitlab_pipeline.m file.

By default, the generate_gitlab_pipeline.m file 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 in the generate_gitlab_pipeline.m file. For example:

padv.pipeline.generatePipeline(op,"myFastFailProcess");

Generate Pipeline in GitLab

Commit and push the MATLAB project to your GitLab repository. By default, GitLab uses .gitlab-ci.yml as the CI/CD configuration file to automatically create pipelines when triggered.

Each time you submit changes to this remote repository, GitLab generates and executes a custom pipeline for your project, process, and pipeline generation options. You do not need to update the .gitlab-ci.yml file when you make changes to your projects or process model. the pipeline generator automatically generates up-to-date pipelines by using the latest project and process model. You only need to update the .gitlab-ci.yml file if you want to change how the pipeline generator organizes and executes the pipeline.

In GitLab, your pipeline contains two upstream jobs:

  • SimulinkPipelineGeneration — Generates a child pipeline file.

  • SimulinkPipelineExecution — Executes the child pipeline file. By default, the child pipeline contains:

    • Jobs for your process, organized by the PipelineArchitecture property specified in padv.pipeline.GitLabOptions.

    • The Generate_PADV_Report job, which generates a Process Advisor build report.

    • The Collect_Artifacts job, which collects build artifacts.

See Also

Functions

Objects

Topics