Configuring GitLab Runner Settings

1. Configuring Runner Tags

Property	Values	Description
tag_list	`["tag1", "tag2"]`	List of tags to assign to the runner. Used to filter jobs to specific runners.

Example: Setting Runner Tags

runner:
  tag_list:
    - "linux"
    - "docker"
    - "production"

Note: Tags must be unique within a GitLab instance and are used to match jobs to runners.

2. Setting Runner Concurrency

Property	Values	Description
concurrent	`1`	Maximum number of jobs that can run concurrently on a runner
max_timeout	`3600`	Maximum time (in seconds) a job can run before being killed

Example: Configuring Runner Concurrency

concurrent: 3
max_timeout: 7200

Note: Setting concurrent higher than the available system resources can lead to performance degradation or job failures.

3. Setting Runner Limits

Limit	Description	Default Value	Notes
concurrent	Maximum number of jobs that can run concurrently on a runner	`1`	Set to `0` for unlimited jobs
max_timeout	Maximum time a job can run before being canceled	`3600`	Value in seconds
idle_timeout	Time a runner waits before shutting down when idle	`60`	Value in seconds
check_interval	How often the runner checks for new jobs	`30`	Value in seconds

Example: Configuring Runner Limits in `config.toml`

[runner]
  concurrent = 5
  max_timeout = 7200
  idle_timeout = 120
  check_interval = 60

4. Configuring Runner Cache

Setting	Description	Default	Notes
cache.enabled	Enables or disables caching	`false`	Set to `true` to enable caching
cache.key	Cache key used to store and retrieve cache	`null`	Can use variables like `$CI_COMMIT_REF_SLUG`
cache.path	Paths to cache and restore	`[]`	Array of paths to include in cache
cache.uncompressed	Whether to compress cache files	`false`	Set to `true` for uncompressed cache

Example: Basic Cache Configuration

cache:
  key: $CI_COMMIT_REF_SLUG
  paths:
    - node_modules/
    - .npm/

Note: Cache is scoped to the project and branch. Changes in cache key or paths will result in a new cache being created.

5. Setting Runner Timeout

Configuration Option	Values	Description
timeout	`3600`	Maximum time (in seconds) a job can run before being canceled

Example: Setting timeout in config.toml

[runner]
  name = "my-runner"
  url = "https://gitlab.example.com/"
  token = "runner-token"
  timeout = 7200

Note: The timeout value is specified in seconds. If a job exceeds this time, GitLab CI/CD will cancel it.

6. Configuring Log Level

Log Level	Description	Usage
debug	Displays all logs including debug information	Use for troubleshooting detailed issues
info	Shows standard operational messages	Default setting for most environments
warn	Logs warnings and errors only	Use for production environments to reduce noise
error	Logs only errors	Minimal logging, useful for monitoring

Example: Setting Log Level in gitlab-runner config

[runner]
  name = "my-runner"
  url = "https://gitlab.example.com/"
  token = "runner-token"
  log_level = "warn"

7. Setting Check Interval

Setting	Description	Default Value	Notes
check_interval	Interval in seconds to check for new jobs	`3`	Controls how frequently the runner polls for new jobs

Example: Configuring check_interval in config.toml

[runner]
  check_interval = 5

8. Configuring Session Server

Setting	Description	Default Value	Notes
session_server	Enables or disables the session server feature for GitLab Runner	`false`	Requires GitLab Runner v15.0+
session_server.port	Port on which the session server listens	`8093`	Must be a valid port number (1-65535)
session_server.host	Host address for the session server	`0.0.0.0`	Use `127.0.0.1` to restrict access to local machine only

Example: Enabling Session Server in config.toml

[session_server]
  enabled = true
  port = 8093
  host = "0.0.0.0"

Note: The session server feature is intended for advanced users who require remote access to running jobs. It should be used with caution and proper security measures in place.

9. Using Runner Feature Flags (FF_*)

Feature Flag	Environment Variable	Description	Status
Runner Feature Flags	`FF_*`	Enable or disable experimental features in GitLab Runner	EXPERIMENTAL

Example: Setting Feature Flags

export FF_TEST_FEATURE=true
export FF_NEW_EXECUTOR=false

Note: Feature flags are intended for testing and may change or be removed in future versions.

10. Configuring Pre-Clone and Post-Clone Scripts

Script Type	Description	Execution Context	Usage Example
pre_clone_script	Runs before the repository is cloned	Runner environment, before clone	`pre_clone_script:` `- echo "Starting clone process"`
post_clone_script	Runs after the repository is cloned	Runner environment, after clone	`post_clone_script:` `- ls -la`

Example: Using pre_clone_script and post_clone_script

stages:
  - build

before_script:
  - echo "Global before script"

pre_clone_script:
  - echo "Pre-clone: Setting up environment"
  - mkdir -p /tmp/build

post_clone_script:
  - echo "Post-clone: Checking files"
  - ls -la

build_job:
  stage: build
  script:
    - echo "Building project"

Note: These scripts execute in the runner's shell environment and can be used to set up or clean up the build environment.