When managing self-hosted or cloud infrastructure for CI/CD pipelines, even a small configuration mistake can lead to unexpected resource consumption, build instability, or failed deployments.
In my recent open-source contribution to GitLab Runner (MR !7782), I addressed a configuration issue involving TOML parsing that could cause runners to execute an unlimited number of jobs unintentionally.
The issue was straightforward: GitLab Runner recognized concurrent and limit, but did not recognize concurrency as an alias for these settings.
In this article, I'll explain the problem, the implementation behind the fix, how I tested it, and why small configuration improvements matter in production infrastructure.
1. The Problem: The Concurrency Trap
GitLab Runner provides two important configuration options for controlling parallel job execution:
-
concurrent: Defines the maximum number of jobs that can run simultaneously across all registered runners. -
limit: Defines the maximum number of builds that an individual runner can execute simultaneously.
However, developers and DevOps engineers commonly use the term concurrency when discussing parallel job execution.
This creates a natural expectation that the following configuration should work:
Global configuration:
concurrency = 4 Individual runner configuration:
[[runners]] name = "docker-runner" url = "https://gitlab.com" concurrency = 1 executor = "docker" The intention is simple:
- Allow a maximum of four concurrent jobs globally.
- Allow the individual Docker runner to execute only one job at a time.
Unfortunately, GitLab Runner did not originally recognize concurrency as an alias for either configuration field.
What actually happened?
GitLab Runner uses Go structures and TOML decoding to load configuration from config.toml.
The relevant configuration fields were mapped using TOML struct tags:
type Config struct { Concurrent int `toml:"concurrent"` } type RunnerConfig struct { Limit int `toml:"limit"` } The decoder mapped configuration keys as follows:
-
concurrent→Config.Concurrent -
limit→RunnerConfig.Limit
Since concurrency was not a recognized configuration key, it could be silently ignored during decoding.
This created an important problem.
For an individual runner, the limit field could remain at its default zero value. In GitLab Runner, a runner limit of 0 means unlimited.
As a result, an operator expecting a single-job execution limit could unintentionally allow multiple builds to run simultaneously.
This could contribute to excessive resource consumption and unexpected infrastructure behavior.
The issue was also associated with GitLab Runner Issue #4793.
2. The Solution: Supporting Concurrency as an Alias
The objective of GitLab Runner MR !7782 was to support concurrency as an alternative configuration key without breaking existing configurations.
The implementation introduced fallback mapping during configuration loading.
The expected behavior is divided into three parts.
A. Global Configuration
If the canonical concurrent key is not explicitly configured, the concurrency alias can populate the global Concurrent field.
concurrency = 4 This allows operators to configure global job concurrency using the more intuitive name.
B. Individual Runner Configuration
Similarly, if the canonical limit key is not explicitly configured, concurrency can populate the individual runner's Limit field.
[[runners]] name = "production-runner" concurrency = 1 This ensures that the runner receives the intended build limit.
C. Backward Compatibility
An important requirement was preserving existing configuration behavior.
If both the canonical key and its alias are provided, the canonical key takes precedence.
| Configuration level | Canonical key | Supported alias |
|---|---|---|
| Global | concurrent | concurrency |
| Individual runner | limit | concurrency |
This approach introduces more flexible configuration while maintaining compatibility with existing deployments.
Example: Updated Configuration
With alias support, operators can now use:
concurrency = 4 [[runners]] name = "production-runner" url = "https://gitlab.com" concurrency = 1 executor = "docker" The configuration can now map the global alias to Concurrent and the runner-level alias to Limit, provided the corresponding canonical keys are not explicitly configured.
3. Testing the Implementation with Table-Driven Tests in Go
Configuration changes require careful testing because different combinations of configuration keys can produce different results.
For this contribution, I added table-driven unit tests named:
TestLoadConfig_ConcurrencyAlias
The test cases cover the following scenarios:
Scenario A: Global alias
Only concurrency is specified at the root level.
Expected result: The value is mapped to Config.Concurrent.
Scenario B: Runner-level alias
Only concurrency is specified inside [[runners]].
Expected result: The value is mapped to RunnerConfig.Limit.
Scenario C: Canonical key precedence
Both canonical keys and their corresponding aliases are provided.
Expected result: The canonical configuration values take precedence.
Scenario D: Default values
The relevant configuration values are not explicitly provided.
Expected result: Existing default behavior is preserved.
The targeted test can be executed using:
go test -v ./common -run '^TestLoadConfig_ConcurrencyAlias$' Table-driven testing makes it easier to validate multiple configuration scenarios without duplicating test logic.
It also helps prevent regressions when configuration-loading behavior changes in the future.
4. Why This Change Matters
Although this contribution involved a relatively small configuration change, it highlights an important principle in infrastructure engineering: configuration behavior should be predictable and understandable.
An unsupported configuration key can be more dangerous than an explicit parsing error when the application silently falls back to default values.
This contribution highlights four important lessons:
- Developer Experience Matters: Configuration options should follow intuitive naming conventions wherever possible.
- Beware of Silent Parsing Failures: Unsupported TOML keys can go unnoticed and leave important configuration fields at their default values.
- Backward Compatibility Is Essential: Introducing aliases should not unexpectedly override existing configuration settings.
- Test Configuration Precedence: Unit tests should cover not only successful parsing but also conflicts between canonical keys and aliases.
Small improvements like these can make infrastructure software more reliable and easier to operate.
5. My Open Source Contribution to GitLab Runner
Contributing to GitLab Runner gave me an opportunity to work on a real-world infrastructure problem involving configuration parsing, Go, TOML decoding, and backward compatibility.
My contribution was merged in GitLab Runner MR !7782 on November 18, 2026.
Contribution: GitLab Runner MR !7782 – Support concurrency alias in configuration
Related Issue: GitLab Runner Issue #4793
Author: Manish Kumar
GitLab: @manishpatel00
Working on open-source infrastructure projects has reinforced an important engineering lesson for me:
Even a small configuration change deserves careful consideration of defaults, compatibility, and real-world operator expectations.
I'm looking forward to contributing more improvements to open-source projects and continuing to learn from real-world engineering challenges.
More open-source contributions and engineering experiences coming soon!


