Install GitLab Runner on macOS

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed

This page contains instructions about installing GitLab Runner on macOS (Apple Silicon and Intel x86-64).

For information about troubleshooting, see Troubleshooting GitLab Runner.

  1. Download the binary for your system:

    • For Intel-based systems: 

      sudo curl --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-amd64"

    • For Apple Silicon-based systems: 

      sudo curl --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"

    You can download a binary for every available version as described in Bleeding Edge - download any other tagged release.

  2. Give it permissions to execute: 

    sudo chmod +x /usr/local/bin/gitlab-runner

  3. In the user account where you will run the GitLab Runner application:

    1. Register a runner configuration. Choose the shell executor during the registration process. When you build iOS or macOS applications on macOS, jobs run directly on the host, and use the identity of the authenticated user. The jobs do not run in a container, which is less secure than using container executors. For details, see the security implications documentation.

    2. Open a terminal and switch to the current user. 

      su - <username>

    3. Install GitLab Runner as a service and start it: 

      cd ~
gitlab-runner install
gitlab-runner start

    See the troubleshooting section for details on resolving potential errors when running these commands.

  4. Reboot your system.

If you followed these instructions, the GitLab Runner configuration file (config.toml) is in /Users/<username>/.gitlab-runner/. Learn more about configuring runners.

For more information, see the glossary.

Limitations on macOS

note
The service needs to be installed from a Terminal window logged in as your current user. Only then can you manage the service.

To sign in as your current user, run the command su - <username> in the terminal. You can obtain your username by running the command ls /users.

Currently, the only proven way for it to work in macOS is by running the service in user-mode.

Because the service runs only when the user is logged in, you should enable auto-login on your macOS machine.

The service is launched as a LaunchAgent. By using LaunchAgents, the builds are able to perform UI interactions, making it possible to run and test in the iOS simulator.

It’s worth noting that macOS also has LaunchDaemons, services running completely in background. LaunchDaemons are run on system startup, but they don’t have the same access to UI interactions as LaunchAgents. You can try to run the Runner’s service as a LaunchDaemon, but this mode of operation is not currently supported.

You can verify that GitLab Runner created the service configuration file after executing the install command, by checking the ~/Library/LaunchAgents/gitlab-runner.plist file.

If Homebrew was used to install git, it may have added a /usr/local/etc/gitconfig file containing: 

[credential]
        helper = osxkeychain

This tells Git to cache user credentials in the keychain, which may not be what you want and can cause fetches to hang. You can remove the line from the system gitconfig with: 

git config --system --unset credential.helper

Alternatively, you can just disable credential.helper for the GitLab user: 

git config --global --add credential.helper ''

You can check the status of the credential.helper with: 

git config credential.helper

Upgrade GitLab Runner

  1. Stop the service: 

    gitlab-runner stop

  2. Download the binary to replace the GitLab Runner executable:

    • For Intel-based systems: 

      sudo curl -o /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-amd64"

    • For Apple Silicon-based systems: 

      sudo curl -o /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"

    You can download a binary for every available version as described in Bleeding Edge - download any other tagged release.

  3. Give it permissions to execute: 

    sudo chmod +x /usr/local/bin/gitlab-runner

  4. Start the service: 

    gitlab-runner start

Upgrade the service file

To upgrade the LaunchAgent configuration, you must uninstall and install the service: 

gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

Using codesign with the GitLab Runner Service

If you installed gitlab-runner on macOS with Homebrew and your build calls codesign, you may have to set <key>SessionCreate</key><true/> to have access to the user keychains. GitLab does not maintain the Homebrew formula and you should use the official binary to install GitLab Runner.

In the following example we run the builds as the gitlab user and want access to the signing certificates installed by that user for codesigning: 

<?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>SessionCreate</key><true/>
    <key>KeepAlive</key>
    <dict>
      <key>SuccessfulExit</key>
      <false/>
    </dict>
    <key>RunAtLoad</key><true/>
    <key>Disabled</key><false/>
    <key>Label</key>
    <string>com.gitlab.gitlab-runner</string>
    <key>UserName</key>
    <string>gitlab</string>
    <key>GroupName</key>
    <string>staff</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/opt/gitlab-runner/bin/gitlab-runner</string>
      <string>run</string>
      <string>--working-directory</string>
      <string>/Users/gitlab/gitlab-runner</string>
      <string>--config</string>
      <string>/Users/gitlab/gitlab-runner/config.toml</string>
      <string>--service</string>
      <string>gitlab-runner</string>
      <string>--syslog</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
  </dict>
</plist>

macOS troubleshooting

The following relate to troubleshooting on macOS.

killed: 9

On Apple Silicon-based systems, you might encounter this error when running the gitlab-runner install, gitlab-runner start, or gitlab-runner register commands.

To resolve these errors, ensure that the directories specified in ~/Library/LaunchAgents/gitlab-runner.plist values StandardOutPath and StandardErrorPath are writable.

In the following example, the /Users/USERNAME/Library/LaunchAgents/gitlab-runner.plist file has been edited to include a new writable directory, gitlab-runner-log, for the log files. 

 <key>StandardErrorPath</key>
  <string>/Users/USERNAME/gitlab-runner-log/gitlab-runner.err.log</string>
 <key>StandardOutPath</key>
  <string>/Users/USERNAME/gitlab-runner-log/gitlab-runner.out.log</string>
</dict>

"launchctl" failed: exit status 112, Could not find domain for

This message may occur when you try to install GitLab Runner on macOS. Make sure that you manage GitLab Runner service from the GUI Terminal application, not the SSH connection.

Failed to authorize rights (0x1) with status: -60007.

If GitLab Runner is stuck on the above message when using macOS, there are two causes to why this happens:

  1. Make sure that your user can perform UI interactions: 

    DevToolsSecurity -enable
sudo security authorizationdb remove system.privilege.taskport is-developer

    The first command enables access to developer tools for your user. The second command allows the user who is member of the developer group to do UI interactions (for example, run the iOS simulator).

  2. Make sure that your GitLab Runner service doesn’t use SessionCreate = true. Previously, when running GitLab Runner as a service, we were creating LaunchAgents with SessionCreate. At that point (Mavericks), this was the only solution to make Code Signing work. That changed recently with OS X El Capitan which introduced a lot of new security features that altered this behavior. Since GitLab Runner 1.1, when creating a LaunchAgent, we don’t set SessionCreate. However, in order to upgrade, you must manually reinstall the LaunchAgent script: 

    gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

    Then you can verify that ~/Library/LaunchAgents/gitlab-runner.plist has SessionCreate set to false.

fatal: unable to access 'https://path:3000/user/repo.git/': Failed to connect to path port 3000: Operation timed out error in the job

If one of the jobs fails with this error, make sure the runner can connect to your GitLab instance. The connection could be blocked by things like:

  • firewalls
  • proxies
  • permissions
  • routing configurations

FATAL: Failed to start gitlab-runner: exit status 134 on gitlab-runner start command

This error indicates that the GitLab Runner service is not installed properly. Run the following commands to resolve the error: 

gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

If the error persists, do a graphical login. A graphical login bootstraps the LaunchAgent, which is required to launch the service. For more details, see Limitations on macOS.

The macOS instances hosted on AWS must perform additional steps to connect to the instance’s GUI. Use the ssh -L option mentioned in the steps to enable SSH port forwarding to allow a remote desktop client, like VNC, to connect to the remote instance. You must also configure AllowTcpForwarding yes in the /private/etc/ssh/sshd_config on the AWS hosted macOS instance. Restart the instance to apply the change to the SSHD configuration. After you sign in to the GUI, repeat the GitLab Runner troubleshooting steps from a terminal in the GUI to resolve the error.

FATAL: Failed to start gitlab-runner: "launchctl" failed with stderr: Load failed: 5: Input/output error on gitlab-runner start command

If this error is encountered when running the gitlab-runner start command, ensure that the directories specified in the ~/Library/LaunchAgents/gitlab-runner.plist values StandardOutPath and StandardErrorPath exist: 

<key>StandardOutPath</key>
<string>/usr/local/var/log/gitlab-runner.out.log</string>
<key>StandardErrorPath</key>
<string>/usr/local/var/log/gitlab-runner.err.log</string>

If the directories do not exist, create them and ensure that the runner service user has appropriate permissions to read and write to them.

ERROR: Error on fetching TLS Data from API response... error error=couldn't build CA Chain

The following error may occur if you upgrade to GitLab Runner v15.5.0 or later: 

Certificate doesn't provide parent URL: exiting the loop  Issuer=Baltimore CyberTrust Root IssuerCertURL=[] Serial=33554617 Subject=Baltimore CyberTrust Root context=certificate-chain-build
Verifying last certificate to find the final root certificate  Issuer=Baltimore CyberTrust Root IssuerCertURL=[] Serial=33554617 Subject=Baltimore CyberTrust Root context=certificate-chain-build
ERROR: Error on fetching TLS Data from API response... error  error=couldn't build CA Chain: error while fetching certificates from TLS ConnectionState: error while fetching certificates into the CA Chain: couldn't resolve certificates chain from the leaf certificate: error while resolving certificates chain with verification: error while verifying last certificate from the chain: x509: “Baltimore CyberTrust Root” certificate is not permitted for this usage runner=x7kDEc9Q

If you encounter this error, you may need to:

  1. Upgrade to GitLab Runner v15.5.1 or later.
  2. Set FF_RESOLVE_FULL_TLS_CHAIN to false in the [runners.feature_flags] configuration. For example: 
    [[runners]]
  name = "ruby-2.7-docker"
  url = "https://CI/"
  token = "TOKEN"
  executor = "docker"
  [runners.feature_flags]
    FF_RESOLVE_FULL_TLS_CHAIN = false

Disabling this feature flag may help resolve TLS connectivity issues for HTTPS endpoints that use a root certificate signed with a SHA-1 signature or some other deprecated algorithm.