Create MacOS gitlab-runner

Installing GitLab Runner with `brew services` (Simplified Method)

This guide details a simplified method for installing and configuring a GitLab Runner on macOS by using Homebrew's built-in service management. This is often easier than manually managing `launchd` files.

1. Install GitLab Runner

First, install the GitLab Runner package using Homebrew:

brew install gitlab-runner

2. Note on Homebrew Paths (Apple Silicon vs. Intel)

Homebrew uses different installation paths depending on your Mac's architecture. The shell environment setup in a later step will handle this automatically by using `brew shellenv`, but it's good to be aware of the difference:

• Apple Silicon (M1/M2/M3): `/opt/homebrew/`
• Intel: `/usr/local/`

3. Create and Switch to the Runner User

For security and isolation, it is best practice to run the GitLab Runner under a dedicated user account. If you haven't created one, you can do so in System Settings > Users & Groups.

Once the user (e.g., `runner`) exists, switch to it for the following steps:

su runner

4. Configure the GitLab Runner

As the `runner` user, configure the runner's behavior by editing its `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 the shell 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]

5. Set Up the Shell Environment

This is the most critical step. For the runner's jobs to find tools and execute correctly, the `runner` user's shell environment must be configured properly.

Create and configure `.bashrc`

nano ~/.bashrc

Add the necessary environment variables and path definitions.

### Brew ###
# This command sets up Homebrew's environment, including the correct PATH.
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"

# Add any other required PATH exports here. The 'brew shellenv' command
# should handle the primary Homebrew paths for your architecture.
export PATH="/Users/runner/Library/Android/sdk/platform-tools:${PATH}"
    
# 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 your `.bashrc` configuration is loaded for new shell sessions.

nano ~/.bash_profile

Add the following lines:

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

6. Start and Manage the Runner with `brew services`

While still logged in as the `runner` user, use the `brew services` commands to manage the GitLab Runner process. This will automatically create and manage the necessary `launchd` service file for you.

To start the service and register it to run at login:

brew services start gitlab-runner

To stop the service:

brew services stop gitlab-runner

To check the status of all your Homebrew services:

brew services list