> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Connect Orka to GitLab CI/CD with the MacStadium integration. Use Shell executors for permanent runners or custom executors for ephemeral, per-pipeline VMs.

How to use GitLab with your Orka environment.

MacStadium provides seamless **[integration between Orka and GitLab](https://github.com/macstadium/orka-integrations/tree/master/GitLab)**.

Both Shell and custom executors are supported. MacStadium provides scripts and a template configuration for custom executors.

<Warning>Orka 3.1.x and above requires version [v2.0.0+](https://github.com/macstadium/orka-integrations/releases/tag/v2.0.0) of the integration.</Warning>

## Set Up a Shell Executor

Shell executors are useful when you need permanent executors that you can reuse across builds.

For the latest information about how to work with a Shell executor in Orka, see [Using a GitLab Shell Executor to Run CI/CD Pipelines in Orka](https://github.com/macstadium/orka-integrations/blob/master/GitLab/shell-executor.md).

## Set Up a Custom Executor

Custom executors are useful when you need to work with ephemeral executors and automate their management. With a custom executor, an executor is created before the pipeline is run and destroyed after the pipeline is complete.

For the latest information about how to work with a custom executor in Orka, see [Using a GitLab Custom Executor to Run CI/CD Pipelines in Orka](https://github.com/macstadium/orka-integrations/blob/master/GitLab/custom-executor.md).

<Note>
  Cache restoration and artifact downloading require the `gitlab-runner` binary to be present inside the Orka VM. If your pipeline logs show "Missing gitlab-runner. Extracting cache is disabled." or "Missing gitlab-runner. Artifacts downloading is disabled.", install the `gitlab-runner` binary in your base image before creating your VM config.
</Note>

## Run concurrent builds

By default, the [config template](https://github.com/macstadium/orka-integrations/blob/master/GitLab/template-config.md) sets `concurrent = 1`, which means only one build runs at a time. To run multiple builds simultaneously, update two settings in your `config.toml`:

* `concurrent` (global): the total number of jobs that can run at the same time across all runners.
* `limit` (per runner, under `[[runners]]`): the maximum number of jobs this specific runner handles concurrently.

Both values should match. For example, to allow 10 concurrent builds:

```toml theme={null}
concurrent = 10

[[runners]]
  name = "orka-runner"
  executor = "custom"
  limit = 10
  ...
```

See the [GitLab Runner advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) for the full list of options.