Skip to main content
Mapagam

Configuring Runner Executors

1. Using Shell Executor

Property Values Description
executor shell Sets the runner to use the shell executor for job execution
shell bash, sh, zsh, powershell Specifies the shell to use for running scripts (default is bash)
environment Array of key-value pairs Allows setting environment variables for the job

Example: Configuring Shell Executor in .gitlab-ci.yml

job_name:
  executor: shell
  shell: bash
  environment:
    - NODE_ENV=production
    - API_URL=https://api.example.com
Note: The shell executor runs jobs directly on the host machine, which means it inherits the environment and can access system resources. Ensure proper security measures are in place.

2. Using Docker Executor

Property Value Description
executor docker Sets the runner to use Docker for job execution
docker.image alpine:latest Base image for the job container
docker.privileged false Run containers in privileged mode (use with caution)
docker.volumes ['/cache'] List of volumes to mount into the container
docker.network_mode bridge Network mode for the container (e.g., bridge, host)

Example: Docker Executor Configuration

runner:
  executor: docker
  docker:
    image: alpine:latest
    privileged: false
    volumes:
      - /cache
    network_mode: bridge
Note: The Docker executor requires Docker to be installed on the runner machine.
Warning: Running containers in privileged mode can pose security risks.

3. Using Kubernetes Executor

Property Value Description
executor kubernetes Specifies the Kubernetes executor for the job
kubernetes.image alpine:latest Base image for the job pod
kubernetes.namespace default Kubernetes namespace to run the job in
kubernetes.service_account gitlab-runner Kubernetes service account to use for the job

Example: Kubernetes Executor Configuration

job_name:
  executor: kubernetes
  kubernetes:
    image: alpine:latest
    namespace: default
    service_account: gitlab-runner
Note: The Kubernetes executor requires the GitLab Runner to be installed in a Kubernetes cluster.
Warning: Ensure that the service account has appropriate RBAC permissions to interact with the Kubernetes API.

4. Using SSH Executor

Property Value Description
executor ssh Sets the runner to use SSH executor
ssh.host hostname SSH host to connect to
ssh.port 22 SSH port to connect to (default: 22)
ssh.user user User to connect as via SSH
ssh.password password Password for SSH authentication (if not using keys)
ssh.key private_key Private key for SSH authentication (recommended)

Example: SSH Executor Configuration

runner:
  executor: ssh
  ssh:
    host: "example.com"
    port: 22
    user: "gitlab-runner"
    key: "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
Note: Ensure the SSH key has appropriate permissions (e.g., 600) and is added to the SSH agent or configured in the runner config.

5. Using VirtualBox Executor

Property Value Description
executor virtualbox Sets the runner to use VirtualBox for job execution
virtualbox.image ubuntu:latest Base image to use for the VirtualBox VM
virtualbox.memory_limit 1GB Maximum memory allocated to the VM
virtualbox.cpu_limit 2 Number of CPUs to allocate to the VM

Example: Configuring VirtualBox Executor

runner:
  executor: virtualbox
  virtualbox:
    image: ubuntu:latest
    memory_limit: 1GB
    cpu_limit: 2
Note: VirtualBox executor is deprecated as of GitLab CI/CD v16.0 and will be removed in future versions.

6. Using Docker Machine Executor

Property Value Description
executor docker-machine Specifies the Docker Machine executor to use for running jobs.
machine.driver amazonec2 Driver used to create and manage Docker Machine instances (e.g., amazonec2, google, azure).
machine.image gitlab/gitlab-runner:latest Docker image to use for the runner instance.
machine.name docker-machine-runner-{{.Node.Name}} Name pattern for Docker Machine instances.
machine.options amazonec2-region=us-east-1 Options specific to the Docker Machine driver (e.g., region, instance type).

Example: Configuring Docker Machine Executor

runner:
  executor: docker-machine
  docker-machine:
    driver: amazonec2
    image: gitlab/gitlab-runner:latest
    name: docker-machine-runner-{{.Node.Name}}
    options:
      amazonec2-region: us-east-1
      amazonec2-instance-type: t3.medium
Note: The Docker Machine executor is deprecated as of GitLab CI/CD v16.0 and will be removed in future versions. It is recommended to migrate to the docker or kubernetes executors.

7. Using Custom Executor

Property Description Values Notes
custom_executor Defines a custom executor for the job true Used in conjunction with executor field to specify custom behavior
script Script to execute in the custom environment ['echo "Running custom script"'] Can be a list of commands or a single command string
before_script Commands to run before the main script ['setup.sh'] Executed in the custom environment before script
after_script Commands to run after the main script ['cleanup.sh'] Executed in the custom environment after script

Example: Custom Executor Configuration

job_name:
  custom_executor: true
  script:
    - echo "Running custom executor job"
    - ./run-tests.sh
  before_script:
    - echo "Setting up environment"
    - ./setup.sh
  after_script:
    - echo "Cleaning up"
    - ./cleanup.sh
Note: Custom executors require the runner to be configured with appropriate capabilities to support custom environments.

8. Configuring Executor-Specific Settings

Executor Configuration Option Description Example Value
shell shell.execute Command to execute scripts /bin/bash -e
shell shell.timeout Script execution timeout in seconds 3600
docker docker.image Docker image to run jobs in alpine:latest
docker docker.privileged Run containers in privileged mode true
docker docker.volumes Volumes to mount into the container ["/cache"]
docker docker.network_mode Docker network mode to use bridge
kubernetes kubernetes.image Container image to use in Kubernetes job alpine:latest
kubernetes kubernetes.namespace Kubernetes namespace to run jobs in default
kubernetes kubernetes.service_account Kubernetes service account to use for job execution gitlab-runner
kubernetes kubernetes.node_selector Node selector labels to restrict job scheduling {"beta.kubernetes.io/os": "linux"}

Example: Docker Executor Configuration

executor: docker
  docker:
    image: alpine:latest
    privileged: true
    volumes:
      - /cache

Example: Kubernetes Executor Configuration

executor: kubernetes
  kubernetes:
    image: alpine:latest
    namespace: default
    service_account: gitlab-runner
    node_selector:
      beta.kubernetes.io/os: linux

9. Configuring Executor Volumes

Property Description Default Value Notes
volume Defines a volume to be mounted into the runner container None Can be specified multiple times for different volumes
mount_path Path inside the container where volume is mounted /tmp Must be an absolute path
read_only Whether the volume is mounted read-only false Boolean value

Example: Configuring Volume Mounts in GitLab CI

job_name:
  script:
    - echo "Running job"
  volumes:
    - type: bind
      source: /host/path
      target: /container/path
      read_only: true
Note: Volumes must be defined in the config.toml file or via environment variables for the runner to recognize them.
Warning: Mounting volumes with read_only: true can prevent write operations to the volume in the container.

10. Managing Executor Security

Example: Configuring Runner Security with Environment Variables

export GITLAB_RUNNER_EXECUTOR="shell"
export GITLAB_RUNNER_REQUEST_CONCURRENT=1
export GITLAB_RUNNER_CHECK_INTERVAL=30
Configuration Option Description Default Value Security Impact
executor Specifies the executor to use for running jobs shell High - Determines job execution environment and access to system resources
request_concurrent Number of concurrent jobs the runner can execute 1 Medium - Limits resource consumption and potential for abuse
check_interval Interval in seconds to check for new jobs 30 Low - Affects responsiveness but not security directly
Note: Ensure that the runner has minimal necessary permissions to avoid privilege escalation.
Warning: Using shell executor with elevated privileges can pose significant security risks.

Security Best Practices for Executor Configuration

  • Use docker or kubernetes executors for better isolation
  • Limit concurrent jobs to prevent resource exhaustion attacks
  • Regularly update runner versions to patch known vulnerabilities
  • Implement strict access controls for runner registration tokens

Was this article helpful?

Related Cheat Sheets