### Custom ENTRYPOINT Script Example

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/docker.md

An example of a shell script that can be used as an ENTRYPOINT. This script starts a Docker daemon and then builds and pushes a specified Docker image.

```shell
#!/bin/sh

dind docker daemon
    --host=unix:///var/run/docker.sock \
    --host=tcp://0.0.0.0:2375 \
    --storage-driver=vf &

docker build -t "$BUILD_IMAGE" .
docker push "$BUILD_IMAGE"
```

--------------------------------

### Install and Start GitLab Runner (User Account)

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/windows.md

Installs GitLab Runner as a Windows service using a specified user account and starts the service. Requires valid username and password. Assumes the current directory is C:\GitLab-Runner.

```powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
.\gitlab-runner.exe start
```

--------------------------------

### Install and Start GitLab Runner (System Account)

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/windows.md

Installs GitLab Runner as a Windows service using the Built-in System Account and starts the service. Assumes the current directory is C:\GitLab-Runner.

```powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start
```

--------------------------------

### Install and Start GitLab Runner Service

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/windows.md

This shell command sequence demonstrates how to install and start the GitLab Runner service on Windows. It includes setting a password and the expected output if the service fails to start due to logon rights.

```shell
gitlab-runner install --password WINDOWS_MACHINE_PASSWORD
gitlab-runner start
FATA[0000] Failed to start GitLab Runner: The service did not start due to a logon failure.
```

--------------------------------

### Install and Start GitLab Runner Service

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/linux-manually.md

Install GitLab Runner as a system service, specifying the user and working directory. Then, start the service to make GitLab Runner operational.

```shell
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start
```

--------------------------------

### Install Homebrew and GitLab Runner

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/macos_setup.md

Install the Homebrew package manager and use it to install and start the GitLab Runner service.

```shell
/bin/bash -c "$(curl "https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh")"
```

```shell
brew install rbenv gitlab-runner
brew services start gitlab-runner
```

--------------------------------

### Setup script for systemd slices

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/slot_based_cgroups.md

Example script to configure systemd slices for slot-based cgroups, including CPU pinning.

```bash
#!/bin/bash
# gitlab-runner-systemd-slice-setup.sh
# Script to set up systemd slices for GitLab Runner slot-based cgroups
# This example configures 4 slots on an 8-core machine, with each slot pinned to 2 CPUs

set -e

MAX_SLOTS=4  # Adjust based on your capacity_per_instance configuration

# CPU pinning configuration (2 CPUs per slot on an 8-core machine)
# Format: comma-separated CPU list for systemd AllowedCPUs
declare -a CPU_ASSIGNMENTS=(
    "0,1"    # Slot 0: CPUs 0 and 1
    "2,3"    # Slot 1: CPUs 2 and 3
    "4,5"    # Slot 2: CPUs 4 and 5
    "6,7"    # Slot 3: CPUs 6 and 7
)

# Check if running as root
if [[ $EUID -ne 0 ]]; then
   echo "This script must be run as root for systemd slice setup"
   exit 1
fi
```

--------------------------------

### Install and start GitLab Runner service

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/osx.md

Registers and initiates the runner service in the user's home directory.

```shell
cd ~
gitlab-runner install
gitlab-runner start
```

--------------------------------

### Dockerfile for Custom ENTRYPOINT

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/docker.md

A Dockerfile example that uses a custom script as the ENTRYPOINT. This setup is for creating a Docker image that executes predefined commands for building other Docker images within a secure environment.

```dockerfile
FROM docker:dind
ADD / /entrypoint.sh
ENTRYPOINT ["/bin/sh", "/entrypoint.sh"]
```

--------------------------------

### Kubernetes Executor Configuration with Lifecycle Hooks

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/kubernetes/_index.md

Example TOML configuration for the Kubernetes executor, demonstrating the setup of container lifecycle hooks for both PostStart (exec) and PreStop (HTTP GET) actions.

```toml
[[runners]]
  name = "kubernetes"
  url = "https://gitlab.example.com/"
  executor = "kubernetes"
  token = "yrnZW46BrtBFqM7xDzE7dddd"
  [runners.kubernetes]
    image = "alpine:3.11"
    privileged = true
    namespace = "default"
    [runners.kubernetes.container_lifecycle.post_start.exec]
      command = ["touch", "/builds/postStart.txt"]
    [runners.kubernetes.container_lifecycle.pre_stop.http_get]
      port = 8080
      host = "localhost"
      path = "/test"
      [[runners.kubernetes.container_lifecycle.pre_stop.http_get.http_headers]]
        name = "header_name_1"
        value = "header_value_1"
      [[runners.kubernetes.container_lifecycle.pre_stop.http_get.http_headers]]
        name = "header_name_2"
        value = "header_value_2"
```

--------------------------------

### Install Dependencies on macOS (Installation Package)

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Install Go using the official package and yq via binary download for macOS.

```shell
wget https://storage.googleapis.com/golang/go1.26.3.darwin-amd64.pkg
open go*-*.pkg
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Example PowerShell Build Script

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/shells/_index.md

A comprehensive PowerShell script demonstrating environment variable setup, directory creation, Git repository cloning, checkout, and cache restoration. It includes error handling for Git commands and conditional logic for cache extraction.

```powershell
$ErrorActionPreference = "Continue" # This will be set to 'Stop' when targetting PowerShell Core

echo "Running on $([Environment]::MachineName)..."

& {
  $CI="true"
  $env:CI=$CI
  $CI_COMMIT_SHA="db45ad9af9d7af5e61b829442fd893d96e31250c"
  $env:CI_COMMIT_SHA=$CI_COMMIT_SHA
  $CI_COMMIT_BEFORE_SHA="d63117656af6ff57d99e50cc270f854691f335ad"
  $env:CI_COMMIT_BEFORE_SHA=$CI_COMMIT_BEFORE_SHA
  $CI_COMMIT_REF_NAME="main"
  $env:CI_COMMIT_REF_NAME=$CI_COMMIT_REF_NAME
  $CI_JOB_ID="1"
  $env:CI_JOB_ID=$CI_JOB_ID
  $CI_REPOSITORY_URL="Z:\Gitlab\tests\test"
  $env:CI_REPOSITORY_URL=$CI_REPOSITORY_URL
  $CI_PROJECT_ID="1"
  $env:CI_PROJECT_ID=$CI_PROJECT_ID
  $CI_PROJECT_DIR="Z:\Gitlab\tests\test\builds\0\project-1"
  $env:CI_PROJECT_DIR=$CI_PROJECT_DIR
  $CI_SERVER="yes"
  $env:CI_SERVER=$CI_SERVER
  $CI_SERVER_NAME="GitLab CI"
  $env:CI_SERVER_NAME=$CI_SERVER_NAME
  $CI_SERVER_VERSION=""
  $env:CI_SERVER_VERSION=$CI_SERVER_VERSION
  $CI_SERVER_REVISION=""
  $env:CI_SERVER_REVISION=$CI_SERVER_REVISION
  $GITLAB_CI="true"
  $env:GITLAB_CI=$GITLAB_CI
  $GIT_SSL_CAINFO=""
  New-Item -ItemType directory -Force -Path "C:\GitLab-Runner\builds\0\project-1.tmp" | out-null
  $GIT_SSL_CAINFO | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
  $GIT_SSL_CAINFO="C:\GitLab-Runner\builds\0\project-1.tmp\GIT_SSL_CAINFO"
  $env:GIT_SSL_CAINFO=$GIT_SSL_CAINFO
  $CI_SERVER_TLS_CA_FILE=""
  New-Item -ItemType directory -Force -Path "C:\GitLab-Runner\builds\0\project-1.tmp" | out-null
  $CI_SERVER_TLS_CA_FILE | Out-File "C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
  $CI_SERVER_TLS_CA_FILE="C:\GitLab-Runner\builds\0\project-1.tmp\CI_SERVER_TLS_CA_FILE"
  $env:CI_SERVER_TLS_CA_FILE=$CI_SERVER_TLS_CA_FILE
  echo "Cloning repository..."
  if( (Get-Command -Name Remove-Item2 -Module NTFSSecurity -ErrorAction SilentlyContinue) -and (Test-Path "C:\GitLab-Runner\builds\0\project-1" -PathType Container) ) {
    Remove-Item2 -Force -Recurse "C:\GitLab-Runner\builds\0\project-1"
  } elseif(Test-Path "C:\GitLab-Runner\builds\0\project-1") {
    Remove-Item -Force -Recurse "C:\GitLab-Runner\builds\0\project-1"
  }

  & "git" "clone" "https://gitlab.com/group/project.git" "Z:\Gitlab\tests\test\builds\0\project-1"
  if(!$?) { Exit $LASTEXITCODE }

  cd "C:\GitLab-Runner\builds\0\project-1"
  if(!$?) { Exit $LASTEXITCODE }

  echo "Checking out db45ad9a as main..."
  & "git" "checkout" "db45ad9af9d7af5e61b829442fd893d96e31250c"
  if(!$?) { Exit $LASTEXITCODE }

  if(Test-Path "..\..\..\cache\project-1\pages\main\cache.tgz" -PathType Leaf) {
    echo "Restoring cache..."
    & "gitlab-runner-windows-amd64.exe" "extract" "--file" "..\..\..\cache\project-1\pages\main\cache.tgz"
    if(!$?) { Exit $LASTEXITCODE }

  } else {
    if(Test-Path "..\..\..\cache\project-1\pages\main\cache.tgz" -PathType Leaf) {
      echo "Restoring cache..."
      & "gitlab-runner-windows-amd64.exe" "extract" "--file" "..\..\..\cache\project-1\pages\main\cache.tgz"
      if(!$?) { Exit $LASTEXITCODE }

    }
  }
}
if(!$?) { Exit $LASTEXITCODE }

& {
  $CI="true"
  $env:CI=$CI
  $CI_COMMIT_SHA="db45ad9af9d7af5e61b829442fd893d96e31250c"
  $env:CI_COMMIT_SHA=$CI_COMMIT_SHA
  $CI_COMMIT_BEFORE_SHA="d63117656af6ff57d99e50cc270f854691f335ad"
  $env:CI_COMMIT_BEFORE_SHA=$CI_COMMIT_BEFORE_SHA
  $CI_COMMIT_REF_NAME="main"
  $env:CI_COMMIT_REF_NAME=$CI_COMMIT_REF_NAME
  $CI_JOB_ID="1"
  $env:CI_JOB_ID=$CI_JOB_ID
  $CI_REPOSITORY_URL="Z:\Gitlab\tests\test"
  $env:CI_REPOSITORY_URL=$CI_REPOSITORY_URL
  $CI_PROJECT_ID="1"
  $env:CI_PROJECT_ID=$CI_PROJECT_ID
  $CI_PROJECT_DIR="Z:\Gitlab\tests\test\builds\0\project-1"
  $env:CI_PROJECT_DIR=$CI_PROJECT_DIR
  $CI_SERVER="yes"
  $env:CI_SERVER=$CI_SERVER
  $CI_SERVER_NAME="GitLab CI"
  $env:CI_SERVER_NAME=$CI_SERVER_NAME
  $CI_SERVER_VERSION=""
  $env:CI_SERVER_VERSION=$CI_SERVER_VERSION
  $CI_SERVER_REVISION=""
  $env:CI_SERVER_REVISION=$CI_SERVER_REVISION
  $GITLAB_CI="true"
  $env:GITLAB_CI=$GITLAB_CI
  $GIT_SSL_CAINFO=""

```

--------------------------------

### Install Dependencies on macOS (Binary Package)

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Install Go runtime and yq using binary downloads for macOS.

```shell
wget https://storage.googleapis.com/golang/go1.26.3.darwin-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Run Development Setup for GitLab Runner

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Execute this command after installing the required binaries to set up your local development environment for GitLab Runner.

```shell
make development_setup
```

--------------------------------

### Install GitLab Runner on Ubuntu

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/runner_autoscale_aws_fargate/_index.md

Prepare directories, add the GitLab Runner repository, and install the gitlab-runner package.

```shell
sudo mkdir -p /opt/gitlab-runner/{metadata,builds,cache}
curl -s "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner
```

--------------------------------

### Podman Build Output Example

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/kubernetes/use_podman_with_kubernetes.md

This is an example of the output from a `podman build` command, showing the progress and potential warnings during the image building process.

```shell
... 

$ podman build . -t playground-bis:testing
time="2024-11-06T16:57:41Z" level=warning msg="Using cgroups-v1 which is deprecated in favor of cgroups-v2 with Podman v5 and will be removed in a future version. Set environment variable `PODMAN_IGNORE_CGROUPSV1_WARNING` to hide this warning."
time="2024-11-06T16:57:41Z" level=warning msg="Using cgroups-v1 which is deprecated in favor of cgroups-v2 with Podman v5 and will be removed in a future version. Set environment variable `PODMAN_IGNORE_CGROUPSV1_WARNING` to hide this warning.
STEP 1/6: FROM docker.io/library/golang:1.24.4 AS builder
Trying to pull docker.io/library/golang:1.24.4...
Getting image source signatures
Copying blob sha256:32d3574b34bd65a6cf89a80e5bd939574c7a9bd3efbaa4881292aaca16d3d0dc

```

--------------------------------

### Start MinIO Cache Server with Docker

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/speed_up_job_execution.md

This command starts a MinIO S3-compatible cache server using Docker. Ensure Docker Engine is installed on the machine. Modify the exposed port and volume mounts as needed. The environment variables set the root user and password for MinIO.

```shell
docker run -d --restart always -p 9005:9000 \
           -v "/.minio":/root/.minio -v /export:/export \
           -e "MINIO_ROOT_USER=<minio_root_username>" 
           -e "MINIO_ROOT_PASSWORD=<minio_root_password>" \
           --name minio \
           minio/minio:latest server /export
```

--------------------------------

### Install Dependencies with Mise

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Navigate to the gitlab-runner directory and use 'mise install' to set up project dependencies.

```shell
cd gitlab-runner
mise install
```

--------------------------------

### Enable and start gitlab-runner service

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/freebsd.md

Enables the gitlab-runner service to start on boot and then starts it immediately.

```shell
sudo sysrc gitlab_runner_enable=YES
sudo service gitlab_runner start
```

--------------------------------

### Execute systemd setup script

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/slot_based_cgroups.md

Commands to make the systemd setup script executable and run it with root privileges.

```shell
chmod +x gitlab-runner-systemd-slice-setup.sh
sudo ./gitlab-runner-systemd-slice-setup.sh
```

--------------------------------

### Execute cgroup setup script

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/slot_based_cgroups.md

Commands to make the cgroup setup script executable and run it with root privileges.

```shell
chmod +x gitlab-runner-cgroup-setup.sh
sudo ./gitlab-runner-cgroup-setup.sh
```

--------------------------------

### Download and Install Docker Machine Binary

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/docker_machine.md

Download, copy, and make the Docker Machine binary executable for installation.

```shell
curl -O "https://gitlab-docker-machine-downloads.s3.amazonaws.com/v0.16.2-gitlab.48/docker-machine-Linux-x86_64"
cp docker-machine-Linux-x86_64 /usr/local/bin/docker-machine
chmod +x /usr/local/bin/docker-machine
```

--------------------------------

### Install Dependencies on FreeBSD

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Install Go, gmake, git, mercurial, and yq using pkg and binary downloads for FreeBSD.

```shell
pkg install go-1.26.3 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Autoscaling Configuration Example

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md

Configure autoscaling parameters for the Instance or Docker Autoscaler executor. This example shows weekday and weekend autoscaling settings.

```toml
[runners.machine]
  IdleCount = 5
  IdleTime = 600
  MaxBuilds = 100
  MachineName = "auto-scale-%s"
  MachineDriver = "google" # Refer to Docker Machine docs on how to authenticate: https://docs.docker.com/machine/drivers/gce/#credentials
  MachineOptions = [
      # Additional machine options can be added using the Google Compute Engine driver.
      # If you experience problems with an unreachable host (ex. "Waiting for SSH"),
      # you should remove optional parameters to help with debugging.
      # https://docs.docker.com/machine/drivers/gce/
      "google-project=GOOGLE-PROJECT-ID",
      "google-zone=GOOGLE-ZONE", # e.g. 'us-central1-a', full list in https://cloud.google.com/compute/docs/regions-zones/
  ]
  [[runners.machine.autoscaling]]
    Periods = ["* * 9-17 * * mon-fri *"]
    IdleCount = 50
    IdleCountMin = 5
    IdleScaleFactor = 1.5 # Means that current number of Idle machines will be 1.5*in-use machines,
                          # no more than 50 (the value of IdleCount) and no less than 5 (the value of IdleCountMin)
    IdleTime = 3600
    Timezone = "UTC"
  [[runners.machine.autoscaling]]
    Periods = ["* * * * * sat,sun *"]
    IdleCount = 5
    IdleTime = 60
    Timezone = "UTC"

```

--------------------------------

### Runner Configuration Example

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/configuring_runner_operator.md

Example of runner configuration settings, specifically highlighting the 'locked' variable.

```yaml
  locked: true # REQUIRED
  tags: ""
  runUntagged: false
  protected: false
  maximumTimeout: 0
```

--------------------------------

### Install Dependencies on Debian/Ubuntu

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Manually install required packages, Go runtime, and yq for Debian/Ubuntu systems.

```shell
sudo apt-get install -y mercurial git-core wget make build-essential
wget https://storage.googleapis.com/golang/go1.26.3.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Complete config.toml Example

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/kubernetes/use_podman_with_kubernetes.md

This is a comprehensive example of a `config.toml` file for GitLab Runner, incorporating settings for Kubernetes, rootless Podman, and FUSE device resource allocation.

```toml
[[runners]]
  [runners.kubernetes]
    host = ""
    bearer_token_overwrite_allowed = false
    pod_termination_grace_period_seconds = 0
    namespace = ""
    namespace_overwrite_allowed = ""
    pod_labels_overwrite_allowed = ""
    service_account_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    node_selector_overwrite_allowed = ".*"
    allow_privilege_escalation = false
    [runners.kubernetes.pod_security_context]
      run_as_non_root = false
    [runners.kubernetes.build_container_security_context]
      run_as_user = 0
      run_as_group = 0
    [[runners.kubernetes.pod_spec]]
      name = "device-fuse"
      patch_type = "strategic"
      patch = '''
        containers:
          - name: build
            resources:
              limits:
                github.com/fuse: 1
      '''

```

--------------------------------

### Prepare Libvirt VM

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/custom_examples/libvirt.md

Initializes the VM environment by creating a disk image, installing the VM via virt-install, and waiting for network and SSH availability.

```shell
# /opt/libvirt-driver/prepare.sh

currentDir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
source ${currentDir}/base.sh # Get variables from base script.

set -eo pipefail

# trap any error, and mark it as a system failure.
trap "exit $SYSTEM_FAILURE_EXIT_CODE" ERR

# Copy base disk to use for Job.
qemu-img create -f qcow2 -b "$BASE_VM_IMAGE" "$VM_IMAGE" -F qcow2

# Install the VM
# To boot VM in UEFI mode, add: --boot uefi
virt-install \
    --name "$VM_ID" \
    --os-variant debian11 \
    --disk "$VM_IMAGE" \
    --import \
    --vcpus=2 \
    --ram=2048 \
    --network default \
    --graphics none \
    --noautoconsole

# Wait for VM to get IP
echo 'Waiting for VM to get IP'
for i in $(seq 1 300); do
    VM_IP=$(_get_vm_ip)

    if [ -n "$VM_IP" ]; then
        echo "VM got IP: $VM_IP"
        break
    fi

    if [ "$i" == "300" ]; then
        echo 'Waited 300 seconds for VM to start, exiting...'
        # Inform GitLab Runner that this is a system failure, so it
        # should be retried.
        exit "$SYSTEM_FAILURE_EXIT_CODE"
    fi

    sleep 1s
done

# Wait for ssh to become available
echo "Waiting for sshd to be available"
for i in $(seq 1 300); do
    if ssh -i /root/.ssh/id_rsa -o StrictHostKeyChecking=no gitlab-runner@$VM_IP >/dev/null 2>/dev/null; then
        break
    fi

    if [ "$i" == "300" ]; then
        echo 'Waited 300 seconds for sshd to start, exiting...'
        # Inform GitLab Runner that this is a system failure, so it
        # should be retried.
        exit "$SYSTEM_FAILURE_EXIT_CODE"
    fi

    sleep 1s
done
```

--------------------------------

### Install Fleeting Plugin Binary

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Use 'go install' to build the executable binary for a Fleeting plugin. Ensure $GOPATH/bin is in your PATH. If using mise, run 'mise reshim' afterwards.

```shell
cd cmd/fleeting-plugin-aws/
go install
```

```shell
mise reshim
```

--------------------------------

### Example config.toml File Structure

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md

A sample `config.toml` file demonstrating global settings and multiple runner configurations.

```toml
# Example `config.toml` file

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file
log_level = "warning"
log_format = "text"
check_interval = 3 # Value in seconds

[[runners]]
  name = "first"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "shell"
  (...)

[[runners]]
  name = "second"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker"
  (...)

[[runners]]
  name = "third"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker-autoscaler"
  (...)


```

--------------------------------

### Configure prepare_exec and prepare_args

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/custom.md

Example of how to define the prepare_exec executable and its arguments in the config.toml file. These arguments are appended to the executable path in the order they are defined.

```toml
...
[runners.custom]
  ...
  prepare_exec = "/path/to/bin"
  prepare_args = [ "Arg1", "Arg2" ]
  ...
```

--------------------------------

### Troubleshooting Specific GitLab Runner Version Installation on Debian/Ubuntu/Mint

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/linux-repository.md

Example of an error message when installing a specific GitLab Runner version without matching helper images.

```shell
sudo apt install gitlab-runner=17.7.1-1
...
The following packages have unmet dependencies:
 gitlab-runner : Depends: gitlab-runner-helper-images (= 17.7.1-1) but 17.8.3-1 is to be installed
E: Unable to correct problems, you have held broken packages.
```

--------------------------------

### Download and Install Fargate Runner Binary

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/runner_autoscale_aws_fargate/_index.md

Download the Fargate runner binary and make it executable. This is the first step in setting up the runner.

```shell
sudo curl -Lo /opt/gitlab-runner/fargate "https://gitlab-runner-custom-fargate-downloads.s3.amazonaws.com/latest/fargate-linux-amd64"
sudo chmod +x /opt/gitlab-runner/fargate
```

--------------------------------

### Example TOML Configuration Template

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/register/_index.md

Create a TOML file with your runner specifications, including executor-specific settings like Kubernetes volumes.

```toml
[[runners]]
  [runners.kubernetes]
  [runners.kubernetes.volumes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty_dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"
```

--------------------------------

### Kubernetes Executor with Multiple Volume Types Configuration

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/kubernetes/_index.md

Example configuration for the GitLab Runner's Kubernetes executor, demonstrating the setup of multiple volume types including hostPath, PVC, ConfigMap, Secret, emptyDir, CSI, and NFS.

```toml
concurrent = 4

[[runners]]
  # usual configuration
  executor = "kubernetes"
  [runners.kubernetes]
    [[runners.kubernetes.volumes.host_path]]
      name = "hostpath-1"
      mount_path = "/path/to/mount/point"
      read_only = true
      host_path = "/path/on/host"
    [[runners.kubernetes.volumes.host_path]]
      name = "hostpath-2"
      mount_path = "/path/to/mount/point_2"
      read_only = true
    [[runners.kubernetes.volumes.pvc]]
      name = "pvc-1"
      mount_path = "/path/to/mount/point1"
    [[runners.kubernetes.volumes.config_map]]
      name = "config-map-1"
      mount_path = "/path/to/directory"
      [runners.kubernetes.volumes.config_map.items]
        "key_1" = "relative/path/to/key_1_file"
        "key_2" = "key_2"
    [[runners.kubernetes.volumes.secret]]
      name = "secrets"
      mount_path = "/path/to/directory1"
      read_only = true
      [runners.kubernetes.volumes.secret.items]
        "secret_1" = "relative/path/to/secret_1_file"
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty-dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"
    [[runners.kubernetes.volumes.csi]]
      name = "csi-volume"
      mount_path = "/path/to/csi/volume"
      driver = "my-csi-driver"
      [runners.kubernetes.volumes.csi.volume_attributes]
        size = "2Gi"
      [[runners.kubernetes.volumes.nfs]]
        name = "nfs"
        mount_path = "/path/to/mount/point"
        read_only = false
        server = "foo.bar.com"
        path = "/path/on/nfs-share"
```

--------------------------------

### Sample .gitlab-ci.yml for macOS

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/macos_setup.md

Example configuration file for running build and test jobs on a macOS runner.

```yaml
stages:
  - build
  - test

variables:
  LANG: "en_US.UTF-8"

before_script:
  - gem install bundler
  - bundle install
  - gem install cocoapods
  - pod install

build:
  stage: build
  script:
    - bundle exec fastlane build
  tags:
    - macos

test:
  stage: test
  script:
    - bundle exec fastlane test
  tags:
    - macos
```

--------------------------------

### Configure Xcode

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/macos_setup.md

Initialize Xcode components and set the active developer directory.

```shell
sudo xcodebuild -runFirstLaunch
```

```shell
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

--------------------------------

### Run a Docker Hub Registry Mirror

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/speed_up_job_execution.md

This command starts a Docker container that acts as a registry proxy for Docker Hub. It's useful for caching Docker images locally to speed up job execution. Ensure Docker Engine is installed on the machine where this command is run.

```shell
docker run -d -p 6000:5000 \
    -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
    --restart always \
    --name registry registry:2
```

--------------------------------

### Azure Scale Set Configuration for Single Job Instances

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/docker_autoscaler.md

Configure GitLab Runner for Azure autoscaling with one job per instance. This setup ensures job isolation and ephemeral instances. Ensure the VM image has Docker Engine installed and that instances do not self-register.

```toml
concurrent = 10

[[runners]]
  name = "docker autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"                                        # use powershell or pwsh for Windows AMIs

  # uncomment for Windows AMIs when the Runner manager is hosted on Linux
  # environment = ["FF_USE_POWERSHELL_PATH_RESOLVER=1"]

  executor = "docker-autoscaler"

  # Docker Executor config
  [runners.docker]
    image = "busybox:latest"

  # Autoscaler config
  [runners.autoscaler]
    plugin = "azure" # for >= 16.11, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # for versions < 17.0, manually install the plugin and use:
    # plugin = "fleeting-plugin-azure"

    capacity_per_instance = 1
    max_use_count = 1
    max_instances = 10

    [runners.autoscaler.plugin_config] # plugin specific configuration (see plugin documentation)
      name = "my-docker-scale-set"
      subscription_id = "9b3c4602-cde2-4089-bed8-889e5a3e7102"
      resource_group_name = "my-resource-group"

    [runners.autoscaler.connector_config]
      username = "azureuser"
      password = "my-scale-set-static-password"
      use_static_credentials = true
      timeout = "10m"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"
```

--------------------------------

### Example Metrics for Static Configuration

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/monitoring/_index.md

Sample metrics output for static runner configurations.

```prometheus
gitlab_runner_concurrent{runner_name="production-runner-1"} 10
gitlab_runner_jobs_running_total{runner_name="staging-runner-1"} 3
```

--------------------------------

### Install Docker Script

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/docker_machine.md

This script is used by Docker Machine to install Docker on a new virtual machine. It checks if Docker is already installed and, if not, downloads and executes the official Docker installation script.

```shell
if ! type docker; then curl -sSL "https://get.docker.com" | sh -; fi
```

--------------------------------

### Start gitlab-runner service without enabling

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/freebsd.md

Starts the gitlab-runner service for the current session without enabling it to start on reboot.

```shell
sudo service gitlab_runner onestart
```

--------------------------------

### gitlab-runner install

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/commands/_index.md

Installs the GitLab Runner as a system or user service.

```APIDOC
## gitlab-runner install

### Description
Installs GitLab Runner as a service. It accepts different sets of arguments depending on the operating system.

### Parameters
#### Options
- **--service** (string) - Optional - Specify service name to use (Default: gitlab-runner)
- **--config** (string) - Optional - Specify a custom configuration file to use
- **--syslog** (boolean) - Optional - Specify if the service should integrate with system logging service (Default: true for non-systemd)
- **--working-directory** (string) - Optional - Specify the root directory where all data is stored when builds are run with the shell executor
- **--user** (string) - Optional - Specify the user that executes the builds (Default: root)
- **--password** (string) - Optional - Specify the password for the user that executes the builds
```

--------------------------------

### Install GitLab Runner with Skeleton Directory (Debian/Ubuntu/Mint)

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/linux-repository.md

To enable the skeleton directory for new GitLab Runner installations on Debian-based systems, explicitly set GITLAB_RUNNER_DISABLE_SKEL to false before installing.

```shell
export GITLAB_RUNNER_DISABLE_SKEL=false; sudo -E apt-get install gitlab-runner
```

--------------------------------

### Configure emptyDir Volume for Builds Directory

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/kubernetes/_index.md

This example shows how to mount an emptyDir volume in memory to the builds directory, which can be useful for faster build operations.

```toml
concurrent = 4

[[runners]]
  # usual configuration
  executor = "kubernetes"
  builds_dir = "/builds"
  [runners.kubernetes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "repo"
      mount_path = "/builds"
      medium = "Memory"
```

--------------------------------

### Install GitLab Runner with Skeleton Directory (RHEL/CentOS/Fedora/Amazon Linux)

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/linux-repository.md

To enable the skeleton directory for new GitLab Runner installations on RHEL-based systems, explicitly set GITLAB_RUNNER_DISABLE_SKEL to false before installing.

```shell
export GITLAB_RUNNER_DISABLE_SKEL=false; sudo -E yum install gitlab-runner
```

--------------------------------

### Install Latest GitLab Runner on Debian/Ubuntu/Mint

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/linux-repository.md

Install the latest version of GitLab Runner using apt.

```shell
sudo apt install gitlab-runner
```

--------------------------------

### Install tzdata on Alpine Linux

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/faq/_index.md

Use this command to install the timezone data package on Alpine Linux.

```shell
# on Linux Alpine
sudo apk add -U tzdata
```

--------------------------------

### Install Dependencies on CentOS

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Manually install required packages, Go runtime, and yq for CentOS systems.

```shell
sudo yum install mercurial wget make
sudo yum groupinstall 'Development Tools'
wget https://storage.googleapis.com/golang/go1.26.3.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Install dpkg-sig on Debian-based distributions

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/linux-repository.md

Installs the dpkg-sig tool, which is used for manually verifying signatures on deb packages.

```shell
apt update && apt install dpkg-sig
```

--------------------------------

### Install GitLab Runner Dependencies

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/development/_index.md

Installs necessary dependencies for GitLab Runner. For FreeBSD, use 'gmake deps'.

```shell
make deps
 mise reshim
```

--------------------------------

### Example Problematic Configuration: Build Limit Bottleneck

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md

Demonstrates a build limit bottleneck where a runner has a low limit and low request concurrency, exacerbated by long polling.

```toml
concurrent = 4

[[runners]]
  name = "limited-runner"
  limit = 2                # Only 2 builds allowed
  request_concurrency = 1  # Only 1 request at a time
  # Creates severe bottleneck: builds at capacity + request slot blocked by long polling
```

--------------------------------

### Create Helper Images Directory

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/install/linux-manually.md

Creates a directory to store helper images and navigates into it. This is a prerequisite for downloading the images.

```shell
mkdir -p /usr/local/bin/out/helper-images
cd /usr/local/bin/out/helper-images
```

--------------------------------

### Configure Session Server in config.toml

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md

Example of a `config.toml` file with the `[session_server]` section configured. This section is global and applies to all runners defined in the file.

```toml
# Example `config.toml` file with session server configured

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file
log_level = "warning"
log_format = "runner"
check_interval = 3 # Value in seconds

[session_server]
  listen_address = "[::]:8093" # Listen on all available interfaces on port `8093`
  advertise_address = "runner-host-name.tld:8093"
  session_timeout = 1800

```

--------------------------------

### Expose Host Devices to Build Containers

Source: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/executors/docker.md

Configure the runner to allow build containers to access host hardware devices. This example exposes the USB device directory.

```toml
[[runners]]
  name = "hardware-runner"
  url = "https://gitlab.com"
  token = "__REDACTED__"
  executor = "docker"
  [runners.docker]
    # All job containers may access the host device
    devices = ["/dev/bus/usb"]

```