Apple Silicon 또는 Intel x86-64 시스템의 macOS에 GitLab Runner를 설치합니다. GitLab 자체는 로컬 또는 원격에서 컨테이너나 가상 머신에서 실행됩니다.

macOS 서비스 모드#

macOS에서 GitLab Runner는 시스템 수준의 LaunchDaemon이 아닌 사용자 모드 LaunchAgent로 실행됩니다. 이것이 유일하게 지원되는 모드입니다.

사용자 모드에서 러너는:

• 루트가 아닌 현재 인증된 사용자로 실행됩니다.
• 해당 사용자가 로그인하면 시작되고 로그아웃하면 중지됩니다.
• iOS 시뮬레이터를 실행하고 코드 서명을 수행하는 데 필요한 사용자의 키체인 및 UI 세션에 액세스할 수 있습니다.
• ~/.gitlab-runner/config.toml에 구성을 저장합니다.

시스템 수준의 LaunchDaemon은 부팅 시 시작되고 루트로 실행되며 사용자 세션에 액세스할 수 없습니다. GitLab Runner는 LaunchDaemon으로 실행하는 것을 지원하지 않습니다.

재부팅 후에도 러너를 사용할 수 있으려면 macOS 머신에서 자동 로그인을 켜세요.

GitLab Runner 설치#

Apple Silicon 또는 Intel x86-64 시스템에서 CI/CD 잡을 실행하기 위해 macOS에 GitLab Runner를 설치합니다.

사전 조건:

• 잡을 실행하는 사용자 계정으로 macOS 머신에 로그인되어 있어야 합니다. 이 절차에는 SSH 세션을 사용하지 마세요. 로컬 GUI 터미널을 사용하세요.

GitLab Runner를 설치하려면:

1. 시스템에 맞는 바이너리를 다운로드합니다:

   • Intel (x86-64)의 경우:

     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"
     

   • Apple Silicon의 경우:

     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"
     

   특정 태그 릴리스용 바이너리를 다운로드하려면 다른 태그 릴리스 다운로드를 참조하세요.

2. 바이너리를 실행 가능하게 만듭니다:

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

3. 러너 구성을 등록합니다. iOS 및 macOS 빌드에는 셸 executor를 사용하세요. 보안에 대한 자세한 내용은 셸 executor의 보안을 참조하세요.

4. GitLab Runner 서비스를 설치하고 시작합니다:

   cd ~
   gitlab-runner install
   gitlab-runner start
   

5. 시스템을 재부팅합니다.

gitlab-runner install 명령은 ~/Library/LaunchAgents/gitlab-runner.plist에 LaunchAgent plist를 생성하고 launchctl에 등록합니다. 오류가 발생하면 트러블슈팅을 참조하세요.

구성 파일 위치#

구성 옵션에 대한 자세한 내용은 고급 구성을 참조하세요.

GitLab Runner 업그레이드#

GitLab Runner를 최신 버전으로 업그레이드하려면:

1. 서비스를 중지합니다:

   gitlab-runner stop
   

2. GitLab Runner 실행 파일을 교체하기 위한 바이너리를 다운로드합니다:

   • Intel (x86-64)의 경우:

     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"
     

   • Apple Silicon의 경우:

     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"
     

   특정 태그 릴리스용 바이너리를 다운로드하려면 다른 태그 릴리스 다운로드를 참조하세요.

3. 바이너리를 실행 가능하게 만듭니다:

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

4. 서비스를 시작합니다:

   gitlab-runner start
   

서비스 파일 업그레이드#

LaunchAgent 구성을 업그레이드하려면 서비스를 제거하고 다시 설치합니다:

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

GitLab Runner에서 codesign 사용#

Homebrew로 GitLab Runner를 설치했고 빌드에서 codesign을 호출한다면, 사용자 키체인에 액세스하기 위해 <key>SessionCreate</key><true/>를 설정해야 할 수 있습니다.

다음 예시에서 러너는 gitlab 사용자로 빌드를 실행하고 해당 사용자의 서명 인증서에 액세스해야 합니다:

<?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에 GitLab Runner를 설치할 때 다음과 같은 문제가 발생할 수 있습니다.

일반적인 트러블슈팅은 GitLab Runner 트러블슈팅을 참조하세요.

오류: killed: 9#

Apple Silicon에서 gitlab-runner install, gitlab-runner start 또는 gitlab-runner register 명령을 실행할 때 이 오류가 발생할 수 있습니다.

이 오류를 해결하려면 ~/Library/LaunchAgents/gitlab-runner.plist의 StandardOutPath 및 StandardErrorPath 디렉터리가 존재하고 쓰기 가능한지 확인하세요. 예를 들어:

<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>

오류: "launchctl" failed: Could not find domain for#

이 오류는 로컬 GUI 터미널 대신 SSH를 통해 GitLab Runner 서비스를 관리할 때 발생합니다.

이 오류를 해결하려면 macOS 머신에서 직접 터미널 애플리케이션을 열고 install 및 start 명령을 실행하세요.

오류: Failed to authorize rights (0x1) with status: -60007#

이 오류에는 두 가지 가능한 원인이 있습니다.

사용자 계정에 개발자 도구 액세스 권한이 없습니다. 액세스 권한을 부여하려면:

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

또는 LaunchAgent plist에서 SessionCreate가 true로 설정되어 있습니다. 이 문제를 해결하려면 서비스를 재설치하세요:

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

~/Library/LaunchAgents/gitlab-runner.plist의 SessionCreate가 이제 false로 설정되어 있는지 확인합니다.

오류: Failed to connect to path port 3000: Operation timed out#

러너가 GitLab 인스턴스에 접근할 수 없습니다. 방화벽, 프록시, 라우팅 구성 또는 연결을 차단하는 권한 문제를 확인하세요.

오류: FATAL: Failed to start gitlab-runner: exit status 134#

이 오류는 GitLab Runner 서비스가 올바르게 설치되지 않았음을 나타냅니다.

이 오류를 해결하려면 서비스를 재설치하세요:

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

오류가 지속되면 SSH 대신 macOS GUI 데스크톱에 로그인하고 터미널에서 명령을 실행하세요. LaunchAgent를 부트스트랩하려면 그래픽 로그인 세션이 필요합니다.

AWS의 macOS 인스턴스의 경우 GUI에 연결하기 위해 AWS 문서를 따르고 해당 세션의 터미널에서 다시 시도하세요.

오류: launchctl failed: Load failed: 5: Input/output error#

gitlab-runner start 명령을 실행할 때 이 오류가 발생하면 먼저 러너가 이미 실행 중인지 확인하세요:

gitlab-runner status

러너가 실행 중이 아니라면 ~/Library/LaunchAgents/gitlab-runner.plist의 StandardOutPath 및 StandardErrorPath 디렉터리가 존재하고 러너의 사용자 계정이 읽기 및 쓰기 액세스 권한을 가지고 있는지 확인합니다. 그런 다음 러너를 시작합니다:

gitlab-runner start

오류: couldn't build CA Chain#

이 오류는 GitLab Runner v15.5.0으로 업그레이드한 후 발생할 수 있습니다. 전체 오류 메시지는 다음과 같습니다:

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

이 오류를 해결하려면:

1. GitLab Runner v15.5.1 이상으로 업그레이드합니다.

2. 업그레이드할 수 없는 경우, [runners.feature_flags] 구성에서 FF_RESOLVE_FULL_TLS_CHAIN을 false로 설정합니다:

   [[runners]]
     name = "example-runner"
     url = "https://gitlab.com/"
     token = "TOKEN"
     executor = "docker"
     [runners.feature_flags]
       FF_RESOLVE_FULL_TLS_CHAIN = false
   

Homebrew Git 자격 증명 헬퍼로 인해 fetch가 중단됨#

Homebrew가 Git을 설치했다면 /usr/local/etc/gitconfig에 credential.helper = osxkeychain 항목이 추가되었을 수 있습니다. 이는 macOS 키체인에 자격 증명을 캐시하여 git fetch가 중단될 수 있습니다.

시스템 전체에서 자격 증명 헬퍼를 제거하려면:

git config --system --unset credential.helper

GitLab Runner 사용자에 대해서만 비활성화하려면:

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

현재 설정을 확인하려면:

git config credential.helper