Summary

This document is to cover the detailed steps to configure a macOS runner to start automatically via launchctl  after a machine restart. This page also covers a possible issue that could occur while using git lfs  on macOS runners and how to resolve it. 

Environment

Bitbucket Pipelines - macOS runners

Diagnosis

Before we dive into the actual issue, it is important to understand the environment in which this error could occur. 

Steps to reproduce:

• When you set up macOS runner as per our document, you'll see the below command to run the startup script,

  ./start.sh --accountUuid {<UUID of workspace>} --repositoryUuid {<UUID of repository>} --runnerUuid {<unique UUID for the new runner>} --OAuthClientId <clientId> --OAuthClientSecret <secret> --runtime macos-bash --workingDirectory ../temp

  In the above command, the values for accountUuid, repositoryUuid, runnerUuid, OAuthClientId, and OAuthClientSecret are automatically populated when you create a runner in the Bitbucket Cloud UI. For security reasons, the values in this example are removed.

• You should create a .plist file with any name, say "pipeline-runner.plist" in your machine under "/Library/LaunchDaemons/". A sample .plist file for your reference, 
  

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
      "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  <plist version="1.0">
  <dict>
      <key>Label</key>
      <string>pipelines.runner</string>
      <key>ServiceDescription</key>
      <string>Bitbucket Pipelines Runner</string>
      <key>WorkingDirectory</key>
      <string>/Users/someuser/Documents/Git/atlassian-bitbucket-pipelines-runner/bin</string>
      <key>ProgramArguments</key>
      <array>   
      	<string>./start.sh</string>
  	<string>--accountUuid</string>
          <string>{accountId}</string>
          <string>--repositoryId</string>
          <string>{repositoryUuid}</string>
  	<string>--runnerUuid</string>
          <string>{runnerId}</string>
  	<string>--OAuthClientId</string>
          <string>ClientId</string>
  	<string>--OAuthClientSecret</string>
          <string>secret</string>
  	<string>--runtime</string>
          <string>macos-bash</string>
  	<string>--workingDirectory</string>
          <string>../temp</string>
      </array>
      <key>RunAtLoad</key>
      <true/>
      <key>UserName</key>
      <string>someuser</string>
      <key>StandardErrorPath</key>
      <string>/Users/someuser/Documents/Git/test/pipelines.err</string>
      <key>StandardOutPath</key>
      <string>/tmp/pipelines.out</string>
      <key>SessionCreate</key>
      <true/>
  </dict>
  </plist>
  
  

  
  

  a. In the above sample .plist file, please replace the values for accountId, repositoryId, runnerId, ClientId, and secret with the actual values from the startup command you get while creating runner in the UI. 
  b. The values for UserName, StandardErrorPath, and StandardOutPath can be any path of your choice.

• Execute the below steps to configure runners to start using launchctl
  

  % launchctl load /Library/LaunchDaemons/pipelines-runner.plist
  % launchctl start /Library/LaunchDaemons/pipelines-runner.plist

  
  Reference: https://somesh-rokz.medium.com/how-to-create-services-in-macos-using-bash-launchctl-and-plutil-commands-step-by-step-guide-d736d25cdeeb

• Upon executing the above commands, the runner should start and appear online in Bitbucket UI. You can check the same from Repository Settings → Runners
• Now that the runner is set up, you can configure a build to be executed on this self-hosted macOS runner as per the instructions on Using your runner

• Below is an example bitbucket-pipelines.yml file using git lfs that could fail the build with "Git LFS must be installed in order to use it in bitbucket-pipelines.yaml" as shown in the screenshot

  image: atlassian/default-image:2
  
  steps:
      - step: &build-test
          clone:
            lfs: true
          runs-on: 
                 - 'self.hosted'
                 - 'macos'
          name: Build and test
          script:
            - echo "testing git lfs"
        
  
  pipelines:   
    custom:
             
      customstep2:   
        - step: *build-test

• Even though git lfs  is installed on your machine where the macOS runner is hosted, there are chances you might run into this error. Attaching a screenshot for your reference, 
  

Cause

The reason for this error could be git-lfs  binary is not present in the path/folder where git from Xcode is installed as git-lfs  might have been installed with brew  command on mac. You can execute the below commands to verify the same.

% git --exec-path ## shows the system git path
/Applications/Xcode.app/Contents/Developer/usr/libexec/git-core

% ls /Applications/Xcode.app/Contents/Developer/usr/libexec/git-core ## check git-lfs is present inside the path. this might be a bit different for your machine

Solution

If you see that the git-lfs  binary is not present in the /Applications/Xcode.app/Contents/Developer/usr/libexec/git-core folder, please use the below command to copy the binary and this should resolve the issue. 

# If git-lfs is not present in the git-core folder, please execute the below command

% sudo ln -s "$(which git-lfs)" "$(git --exec-path)/git-lfs"