Create MacOS gitlab-runner

Installing GitLab Runner on macOS via Homebrew

This guide details a method for installing and configuring a GitLab Runner on macOS to run as a dedicated user service.

1. Switch to the Runner User

For security and isolation, it's best to run the GitLab Runner under a dedicated user account (e.g., `runner`).

su runner

2. Create a Custom `launchd` Service File

Create a custom `.plist` file in the user's `LaunchAgents` directory to manage the runner process. Run this command to create and edit the file:

nano ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist

Paste the following XML configuration into the file. This configuration ensures the runner starts at login and stays running.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>KeepAlive</key>
        <true/>
        <key>Label</key>
        <string>homebrew.mxcl.gitlab-runner</string>
        <key>LegacyTimers</key>
        <true/>
        <key>LimitLoadToSessionType</key>
        <array>
                <string>Aqua</string>
                <string>Background</string>
                <string>LoginWindow</string>
                <string>StandardIO</string>
                <string>System</string>
        </array>
        <key>ProcessType</key>
        <string>Interactive</string>
        <key>ProgramArguments</key>
        <array>
                <string>/opt/homebrew/opt/gitlab-runner/bin/gitlab-runner</string>
                <string>run</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>WorkingDirectory</key>
        <string>/Users/runner</string>
        <key>StandardErrorPath</key>
        <string>/Users/runner/gitlab-runner.err.log</string>
        <key>StandardOutPath</key>
        <string>/Users/runner/gitlab-runner.out.log</string>
</dict>
</plist>

3. Configure the GitLab Runner

Next, configure the runner's behavior by editing its main configuration file. Create or edit the `config.toml` file:

nano ~/.gitlab-runner/config.toml

Add the following configuration. Note: GitLab Runner does not support Zsh as a shell for its jobs, so you must explicitly set it to `bash`.

concurrent = 3
check_interval = 30
[session_server]
  session_timeout = 1800
[[runners]]
  name = "Mac-mini-runner"
  limit = 1
  url = "https://gitlab.com/"
  token = "masked"
  executor = "shell"
  shell="bash"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]

4. Set Up the Shell Environment

To ensure the shell executor has the correct environment variables and paths, you must configure the `.bashrc` and `.bash_profile` files for the `runner` user.

Create and configure `.bashrc`

nano ~/.bashrc

Add your required environment setup. This is crucial for tools like Homebrew, rbenv, Android SDK, and Fastlane to work correctly in CI/CD jobs.

### Brew ###
## Silicon
eval $(/opt/homebrew/bin/brew shellenv)

### Ruby ###
eval "$(rbenv init -)"

### Extra environments ###
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

# Android
export ANDROID_HOME="/Users/runner/Library/Android/sdk"

# Java
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

# Path
export PATH=/Users/runner/.rbenv/shims:/Users/runner/Downloads/flutter/bin:/opt/homebrew/bin:/opt/homebrew/opt/ruby/bin:/opt/homebrew/lib/ruby/gems/3.2.0/bin:/Users/runner/.rbenv/shims:/opt/homebrew/bin:/opt/homebrew/sbin:/Library/flutter/bin:/Library/flutter/.pub-cache/bin:/Users/runner/.pub-cache/bin:/Users/runner/Library/Android/sdk/bundle-tool/:/Users/runner/Library/Android/sdk/platform-tools/:/Users/runner/Library/Android/sdk/cmdline-tools/latest/bin/:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/Library/Apple/usr/bin
    
# FASTLANE
export FASTLANE_SESSION=masked
export FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="masked"
export FASTLANE_USER="mobil@example.com"
export FASTLANE_PASSWORD="masked"
export SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA=true
export SUPPLY_UPLOAD_MAX_RETRIES=5

Create `.bash_profile` to source `.bashrc`

This ensures that your `.bashrc` configuration is loaded every time a new shell session starts.

nano ~/.bash_profile

Add the following lines:

#####
# USE "~/.bashrc" for configuration!
#####
### Import .bashrc ###
if [ -f ~/.bashrc ]; then
    . ~/.bashrc
fi

5. Start and Manage the Runner Service

Finally, use `launchctl` to load your custom service file, which will start the GitLab Runner.

To enable and run the service:

launchctl load ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist

To disable and stop the service (for maintenance or updates):

launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist