5. Configuring a GitLab Runner

GitLab runners perform jobs defined in a GitLab pipeline. Runners should be hosted separately from the GitLab server instance, with their own computing resources, and they communicate with server instance via HTTPS. Communication is always initiated by the runner. Each runner is registered with the server instance and polls the instance every few seconds to check for jobs. If a runner has all tags required for a job, it can pick up the job.

A GitLab runner uses an executor to run a job. Many executor implementations are provided and consideration of their relative merits is outside the scope of this document. To use Reactis in an executor based on a container (e.g. Docker) or a virtual machine (e.g. VirtualBox, Parallels), a floating license is required. A machine that has a node-locked Reactis license can be configured as a runner by using the Shell executor. However, the Shell executor is not secure and should be used only in trusted environments.

A runner must be able to process the commands in the script directive of a pipeline job. By default, a runner on a Unix system expects a Bash script and a runner on a Windows system expects a Powershell script. Generally, mixing Unix and Windows runners would require separate jobs for each type of runner but, when CI/CD checks are written as MATLAB scripts, a job script that simply invokes MATLAB may be valid for both Bash and Powershell.

In the example in the next section, the CI/CD checks are written as MATLAB scripts that use the Reactis API to run Reactis. This allows Reactis functions to be combined with other MATLAB features. Each job has a script of the form matlab -batch "<matlab-script>" which can be used with both Unix and Windows runners. To run these jobs, the runner requires MATLAB and Reactis to be installed such that the command matlab starts the required version of MATLAB with the Reactis API in the MATLAB path.

5.1. Docker Executor

For a Docker executor, you can create a Reactis Docker image, which is based on a MATLAB Docker image. Note that this uses Linux versions of MATLAB and Reactis. The image is preconfigured to make the Reactis API available in MATLAB.

5.2. Other Executors

For other types of executor, you can perform a standard Reactis installation, using either the Windows installer or the Linux installer. Once installed, the runner must be configured so that a job can use the command matlab to start MATLAB with the Reactis API in the MATLAB path.

To start MATLAB using the command matlab, the MATLAB bin directory should be added to the system environment variable PATH.

To use the Reactis API in MATLAB, the MATLAB path must include the directory lib/api/MATLAB/reactis from the Reactis distribution, as described in the User’s Guide.

Note that if concurrency is set to a value greater than 1 in the runner configuration, the runner may run multiple jobs concurrently. Although this would invoke separate instances of Reactis and MATLAB, any global resources use by these tools will be shared between the jobs. This could lead to race conditions on the global resources such as the Reactis INI file, that all Reactis instances use. Therefore, it is recommended that concurrency is set to 1.

5.2.1. Linux Example

For a runner using the Shell executor, the environment required to process a job script of the form

matlab -batch "<matlab-script>"

can be created by adding the following entry to the runner configuration file /etc/gitlab-runner/config.toml:

  pre_build_script = '''
    export PATH=/opt/matlab/R2025a/bin:"${PATH}"
    export MATLABPATH=/opt/reactis/V2025.2/lib/api/MATLAB/reactis
  '''

In this example, the MATLAB home directory is /opt/matlab/R2025a and the Reactis home directory is /opt/reactis/V2025.2.

For example, the full configuration for a Shell executor in /etc/gitlab-runner/config.toml could be as follows:

concurrent = 1
check_interval = 0
connection_max_age = "15m0s"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "runner-1"
  url = "https://gitlab.example.com/"
  id = 4
  token = "glrt-..."
  token_obtained_at = 2025-12-17T20:50:43Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "shell"
  shell = "bash"
  pre_build_script = '''
    export PATH=/opt/matlab/R2025a/bin:"$PATH"
    export MATLABPATH=/opt/reactis/V2025.2/lib/api/MATLAB/reactis
  '''
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]