How to Unlock Parallel Job Execution in GitLab Runner

In fast‑paced software development, the speed of CI/CD directly impacts delivery efficiency. When many developers push changes simultaneously, a serial runner forces later commits to wait, wasting time and morale. Enabling parallel job execution on a single GitLab Runner instance can dramatically shorten feedback cycles.

Core Configuration: concurrent Parameter

The global concurrent setting in config.toml defines the total number of jobs a single Runner process can run at once. By default it is 1, which is why new installations appear serial. concurrent is a global limit for the entire gitlab-runner process. For example, setting it to 10 caps the combined job count of all executors at ten.

How to Configure concurrent

Edit the config.toml file. Its location varies:

Linux (root install): /etc/gitlab-runner/config.toml Linux (non‑root install): ~/.gitlab-runner/config.toml Other systems: locate config.toml in the Runner installation directory.

At the top of the file, add or modify the concurrent entry:

# Global configuration
concurrent = 4
check_interval = 0
[session_server]
  session_timeout = 1800
[[runners]]
  name = "my-docker-runner"
  url = "https://gitlab.com/"
  token = "your-runner-token"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
  limit = 4

Here concurrent = 4 sets the global cap, while the limit inside the runner block restricts this specific executor to four jobs. A good practice is to keep the sum of all executor limit values equal to or lower than the global concurrent value.

After editing, restart the GitLab Runner service for changes to take effect.

Visualizing Parallel Processing

An activity diagram (illustrated in the article) shows that when concurrent is set to 4, the Runner checks current load and schedules new jobs immediately if fewer than four are running; otherwise jobs wait in a queue.

Using parallel in .gitlab-ci.yml

The parallel keyword in the pipeline definition works together with the Runner's concurrent limit. parallel specifies how many instances a particular job should be split into.

test_job:
  stage: test
  script:
    - echo "Running test part $CI_NODE_INDEX/$CI_NODE_TOTAL"
    - # run test suite
  parallel: 5

If the Runner's concurrent value is at least 5, all five job instances run simultaneously; otherwise they are throttled according to the global limit.

Conclusion

Unlocking parallel processing in GitLab Runner hinges on correctly setting the concurrent parameter in config.toml and optionally using the parallel keyword in .gitlab-ci.yml for finer control. Adjust these values based on the host's CPU and memory to avoid resource exhaustion and maintain job stability.