Create MacOS gitlab-runner - Revision history

Gyurci08: Gyurci08 moved page Create macOS gitlab-runner to Create MacOS gitlab-runner

2025-08-29T11:07:53Z

Gyurci08 moved page Create macOS gitlab-runner to Create MacOS gitlab-runner

← Older revision	Revision as of 11:07, 29 August 2025
(No difference)

Gyurci08 at 11:01, 29 August 2025

2025-08-29T11:01:40Z

← Older revision		Revision as of 11:01, 29 August 2025
Line 10:		Line 10:
	</syntaxhighlight>		</syntaxhighlight>

	=== 2. Note on ~~Homebrew~~ Paths (Apple Silicon vs. Intel) ===		=== 2. Note on 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:		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~~/`		* '''Apple Silicon (M1/M2/M3):''' `/opt/`
	* '''Intel:''' `/usr/local/`		* '''Intel:''' `/usr/local/`

Gyurci08 at 10:59, 29 August 2025

2025-08-29T10:59:37Z

← Older revision		Revision as of 10:59, 29 August 2025
Line 107:		Line 107:

	=== 6. Start and Manage the Runner with `brew services` ===		=== 6. Start and Manage the Runner with `brew services` ===
	'''Crucial Point:''' You must run these commands as the `runner` user. This ensures the service runs under the correct user account~~[2]~~.		'''Crucial Point:''' You must run these commands as the `runner` user. This ensures the service runs under the correct user account.

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

Gyurci08 at 10:58, 29 August 2025

2025-08-29T10:58:47Z

← Older revision		Revision as of 10:58, 29 August 2025
Line 19:		Line 19:
	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'''.		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:		Once the user (e.g., `runner`) exists, '''switch to it for all subsequent steps''':
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	su runner		su runner
Line 107:		Line 107:

	=== 6. Start and Manage the Runner with `brew services` ===		=== 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~~.		'''Crucial Point:''' You must run these commands as the `runner` user. This ensures the service runs under the correct user account[2].

	To start the service and register it to run at login:		To start the service and register it to run automatically at login:
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	brew services start gitlab-runner		brew services start gitlab-runner

Gyurci08 at 10:56, 29 August 2025

2025-08-29T10:56:29Z

Show changes

Gyurci08 at 10:53, 29 August 2025

2025-08-29T10:53:58Z

← Older revision		Revision as of 10:53, 29 August 2025
Line 4:		Line 4:
	This guide details a method for installing and configuring a GitLab Runner on macOS to run as a dedicated user service.		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 ===		=== 1. Install GitLab Runner ===
			First, install the GitLab Runner package using Homebrew:
			<syntaxhighlight lang="bash">
			brew install gitlab-runner
			</syntaxhighlight>

			=== 2. Note on Homebrew Paths (Apple Silicon vs. Intel) ===
			Homebrew uses different installation paths depending on your Mac's architecture. You '''must''' use the correct path in the following configuration files.

			* '''Apple Silicon (M1/M2/M3):''' The path is `/opt/homebrew/`.
			* '''Intel:''' The path is `/usr/local/`.

			The examples in this guide use the Apple Silicon path. Remember to change `/opt/homebrew/` to `/usr/local/` if you are on an Intel-based Mac.

			=== 3. 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`).		For security and isolation, it's best to run the GitLab Runner under a dedicated user account (e.g., `runner`).
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
Line 10:		Line 24:
	</syntaxhighlight>		</syntaxhighlight>

	=== 2. Create a Custom `launchd` Service File ===		=== 4. 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:~~		This process uses `launchd`, the standard service manager on macOS. For more general information, see the [[https://wiki.jandzsogyorgy.hu/index.php/MacOS_Services\|macOS Services (launchd)]] page.

			Create a custom `.plist` file in the user's `LaunchAgents` directory to manage the runner process.
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	nano ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist		nano ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist
	</syntaxhighlight>		</syntaxhighlight>
	Paste the following XML configuration ~~into the file~~. ~~This configuration ensures~~ the ~~runner starts at login and stays running~~.		Paste the following XML configuration. '''Important:''' If you are on an Intel Mac, change the `ProgramArguments` string from `/opt/homebrew/` to `/usr/local/`.
	<syntaxhighlight lang="xml">		<syntaxhighlight lang="xml">
	<?xml version="1.0" encoding="UTF-8"?>		<?xml version="1.0" encoding="UTF-8"?>
Line 39:		Line 55:
	<key>ProgramArguments</key>		<key>ProgramArguments</key>
	<array>		<array>
			<!-- This path is for Apple Silicon. Change to /usr/local/ for Intel. -->
	<string>/opt/homebrew/opt/gitlab-runner/bin/gitlab-runner</string>		<string>/opt/homebrew/opt/gitlab-runner/bin/gitlab-runner</string>
	<string>run</string>		<string>run</string>
Line 54:		Line 71:
	</syntaxhighlight>		</syntaxhighlight>

	=== 3. Configure the GitLab Runner ===		=== 5. Configure the GitLab Runner ===
	Next, configure the runner's behavior by editing its ~~main configuration file. Create or edit the~~ `config.toml` file:		Next, configure the runner's behavior by editing its `config.toml` file.
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	nano ~/.gitlab-runner/config.toml		nano ~/.gitlab-runner/config.toml
Line 79:		Line 96:
	</syntaxhighlight>		</syntaxhighlight>

	=== 4. Set Up the Shell Environment ===		=== 6. 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.		To ensure the shell executor has the correct environment variables, configure the `.bashrc` and `.bash_profile` files for the `runner` user.

	==== Create and configure `.bashrc` ====		==== Create and configure `.bashrc` ====
Line 86:		Line 103:
	nano ~/.bashrc		nano ~/.bashrc
	</syntaxhighlight>		</syntaxhighlight>
	Add your required environment setup. ~~This is crucial for tools like Homebrew, rbenv, Android SDK,~~ and ~~Fastlane~~ to ~~work correctly in CI/CD jobs~~.		Add your required environment setup. The `brew shellenv` command and the `PATH` variable are especially important to get right for your architecture.
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	### Brew ###		### Brew ###
	## Silicon		# Use the correct path for your architecture.
			# Apple Silicon
	eval $(/opt/homebrew/bin/brew shellenv)		eval $(/opt/homebrew/bin/brew shellenv)
			# Intel
			# eval $(/usr/local/bin/brew shellenv)

	### Ruby ###		### Ruby ###
Line 105:		Line 125:
	export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"		export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

	# Path		# Path (ensure /opt/homebrew/bin or /usr/local/bin is included)
	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		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

Line 118:		Line 138:

	==== Create `.bash_profile` to source `.bashrc` ====		==== Create `.bash_profile` to source `.bashrc` ====
	This ensures ~~that~~ your `.bashrc` configuration is loaded ~~every time a~~ new shell ~~session starts~~.		This ensures your `.bashrc` configuration is loaded for new shell sessions.
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	nano ~/.bash_profile		nano ~/.bash_profile
Line 133:		Line 153:
	</syntaxhighlight>		</syntaxhighlight>

	=== 5. Start and Manage the Runner Service ===		=== 7. Start and Manage the Runner Service ===
	Finally, use `launchctl` to load your custom service file, which will start the GitLab Runner.		Finally, use `launchctl` to load your custom service file, which will start the GitLab Runner.

Line 141:		Line 161:
	</syntaxhighlight>		</syntaxhighlight>

	To disable and stop the service ~~(for maintenance or updates)~~:		To disable and stop the service:
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist		launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist
	</syntaxhighlight>		</syntaxhighlight>

Gyurci08 at 10:51, 29 August 2025

2025-08-29T10:51:08Z

Show changes

Gyurci08: Created page with "Category:MacOS h1. MacOS Gitlab-runner h2. MacOS services (launchctl) h3. Description LaunchAgents: Invoked only when the user logs into a graphical session LaunchDaemons: Invoked when the system boots and runs outside of a specific user session. h3. Namespaces h4. System /Library/LaunchAgents: Per-user agents provided by the administrator. /Library/LaunchDaemons: System-wide daemons provided by the administrator. h4. Use..."

2025-07-17T12:15:56Z

Created page with "Category:MacOS h1. MacOS Gitlab-runner h2. MacOS services (launchctl) h3. Description LaunchAgents: Invoked only when the user logs into a graphical session LaunchDaemons: Invoked when the system boots and runs outside of a specific user session. h3. Namespaces h4. System /Library/LaunchAgents: Per-user agents provided by the administrator. /Library/LaunchDaemons: System-wide daemons provided by the administrator. h4. Use..."

New page

[[Category:MacOS]]

h1. MacOS Gitlab-runner

h2. MacOS services (launchctl)

h3. Description

LaunchAgents: Invoked only when the user logs into a graphical session
LaunchDaemons: Invoked when the system boots and runs outside of a specific user session.

h3. Namespaces

h4. System

/Library/LaunchAgents: Per-user agents provided by the administrator.
/Library/LaunchDaemons: System-wide daemons provided by the administrator.

h4. User

~/Library/LaunchAgents: Per-user agents provided by the user.

h3. Examples

h2. Gitlab-runner (homebrew)

<pre><code class="bash">
su runner
</code></pre>

<pre><code class="bash">
nano ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist
</code></pre>

<pre><code class="xml">
<?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>
</code></pre>

<pre><code class="bash">
nano ~/.gitlab-runner/config.toml
</code></pre>

Gitlab-runner does not support zsh as shell!
<pre><code class="toml">
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]
</code></pre>

We need to create .bashrc
<pre><code class="bash">
nano ~/.bashrc
</code></pre>

<pre><code class="bash">
### 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
</code></pre>

We need to create .bash_profile too
<pre><code class="bash">
nano ~/.bash_profile
</code></pre>

<pre><code class="bash">
#####
# USE "~/.bashrc" for configuration!
#####

### Import .bashrc ###
if [ -f ~/.bashrc ]; then
. ~/.bashrc
fi
</code></pre>

Enable and run:
<pre><code class="bash">
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist
</code></pre>

Disable and stop:
<pre><code class="bash">
launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner-custom.plist
</code></pre>