Windows에 GitLab Runner 설치하기

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

Windows에 GitLab Runner를 설치하고 실행하려면 다음이 필요합니다:

  • 공식 사이트에서 설치할 수 있는 Git
  • 사용자 계정의 비밀번호(사용자 계정 대신 기본 시스템 계정에서 실행하려는 경우)

설치

경고: GitLab Runner 10부터 실행 파일이 gitlab-runner로 이름이 변경되었습니다.

  1. 시스템의 어딘가에 폴더를 만듭니다. 예: C:\GitLab-Runner.
  2. 64비트 또는 32비트용 바이너리를 다운로드하여 만든 폴더에 넣습니다. 다음은 바이너리를 gitlab-runner.exe로 이름을 변경했다고 가정합니다(선택 사항). 다음은 Bleeding Edge - 다른 버전 다운로드에 설명된대로 사용 가능한 각 버전에 대한 바이너리를 다운로드할 수 있습니다.
  3. GitLab Runner 디렉토리와 실행 파일에 대한 쓰기 권한을 제한해야 합니다. 이러한 권한을 설정하지 않으면 일반 사용자가 자신의 실행 파일로 교체하고 escalated 권한으로 임의의 코드를 실행할 수 있습니다.
  4. 올려진 명령 프롬프트를 실행합니다.
  5. 등록 러너.

  6. GitLab Runner를 서비스로 설치하고 시작합니다. 서비스를 실행하는 데 기본 시스템 계정(권장) 또는 사용자 계정을 사용할 수 있습니다.

    기본 시스템 계정을 사용하여 서비스 실행 (위에서 만든 폴더인 경우, 예: C:\GitLab-Runner) 

    cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start

    사용자 계정을 사용하여 서비스 실행 (위에서 만든 폴더인 경우, 예: C:\GitLab-Runner)

    현재 사용자 계정의 유효한 암호를 입력해야 하므로 Windows에서 서비스를 시작하려면: 

    cd C:\GitLab-Runner
.\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
.\gitlab-runner.exe start

    GitLab Runner 설치 중에 오류가 발생하면 문제 해결 섹션을 참조하십시오.

  7. (선택 사항) C:\GitLab-Runner\config.toml의 러너 concurrent 값을 업데이트하여 고급 구성 세부 정보에 설명된 바와 같이 여러 동시 작업을 허용합니다. 또한 고급 구성 세부 정보를 사용하여 배치 대신 Bash 또는 PowerShell을 사용하는 쉘 실행기를 업데이트할 수 있습니다.

성공! 러너가 설치되었고 실행되며 시스템 재부팅 후에도 다시 시작됩니다. 로그는 Windows 이벤트 로그에 저장됩니다.

업데이트

  1. 서비스를 중지합니다 (올려진 명령 프롬프트가 필요합니다): 

    cd C:\GitLab-Runner
.\gitlab-runner.exe stop

  2. 64비트 또는 32비트용 바이너리를 다운로드하여 러너 실행 파일을 교체합니다. Bleeding Edge - 다른 버전 다운로드에 설명된대로 사용 가능한 각 버전에 대한 바이너리를 다운로드할 수 있습니다.

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

    .\gitlab-runner.exe start

제거

올려진 명령 프롬프트에서: 

cd C:\GitLab-Runner
.\gitlab-runner.exe stop
.\gitlab-runner.exe uninstall
cd ..
rmdir /s GitLab-Runner

Windows 문제 해결

FAQ 섹션을 읽어서 GitLab Runner의 가장 일반적인 문제 몇 가지에 대해 알아보세요.

계정 이름이 잘못되었다는 오류가 발생하면 사용자 이름 앞에 .\를 추가해 보세요. 

.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"

서비스를 시작하는 중에 로그온 실패로 서비스를 시작하지 못했습니다 오류가 발생하면 문제를 해결하는 방법을 확인하기 위해 FAQ를 참조하세요.

Windows 비밀번호가 없으면 GitLab Runner 서비스가 시작되지 않지만 기본 시스템 계정을 사용할 수 있습니다.

기본 시스템 계정에 문제가 있는 경우, Microsoft의 지원 웹사이트에서 내장 시스템 계정으로 서비스 시작 구성을 읽어보세요.

Runner 로그 가져오기

.\gitlab-runner.exe install을 실행하면 gitlab-runner를 Windows 서비스로 설치합니다. Provider 이름이 gitlab-runner인 이벤트 뷰어에서 로그를 찾을 수 있습니다.

GUI에 액세스할 수 없는 경우, PowerShell에서 Get-WinEvent을 실행할 수 있습니다. 

PS C:\> Get-WinEvent -ProviderName gitlab-runner

   ProviderName: gitlab-runner

TimeCreated                     Id LevelDisplayName Message
-----------                     -- ---------------- -------
2/4/2021 6:20:14 AM              1 Information      [session_server].listen_address not defined, session endpoints disabled  builds=0...
2/4/2021 6:20:14 AM              1 Information      listen_address not defined, metrics & debug endpoints disabled  builds=0...
2/4/2021 6:20:14 AM              1 Information      Configuration loaded                                builds=0...
2/4/2021 6:20:14 AM              1 Information      Starting multi-runner from C:\config.toml...        builds=0...

Windows에서 빌드 중 PathTooLongException 발생

이는 npm과 같은 도구에 의해 때때로 260자 이상의 길이로 경로가 생성되므로 발생합니다. 문제를 해결하기 위해 두 가지 가능한 해결 방법이 있습니다.

a) core.longpaths가 활성화된 Git 사용

먼저 명령줄에서 git config --system core.longpaths true를 실행하고 프로젝트를 GitLab CI 프로젝트 설정 페이지에서 git fetch를 사용하도록 설정하여 문제를 피할 수 있습니다.

b) PowerShell에 NTFSSecurity 도구 사용

NTFSSecurity PowerShell 모듈은 긴 경로를 지원하는 Remove-Item2 메서드를 제공합니다. GitLab Runner가 사용 가능하면 자동으로 사용합니다.

Windows BASH 스크립트 실행이 안될 때; The system cannot find the batch label specified - buildscript

.gitlab-ci.yml에서 Batch 파일 라인 앞에 call을 추가해야 합니다. 예를 들어 다음과 같이 보입니다: 

before_script:
  - call C:\path\to\test.bat

추가 정보는 이슈 #1025에서 확인할 수 있습니다.

웹 터미널에서 색상 출력을 어떻게 얻을 수 있나요?

간단한 답변:

프로그램 출력에 ANSI 색상 코드가 있는지 확인하세요. 텍스트 포맷팅의 목적으로 UNIX ANSI 터미널 에뮬레이터(웹UI 출력에서 사용되는 것)에서 실행 중이라고 가정하세요.

상세한 답변:

GitLab CI의 웹 인터페이스는 UNIX ANSI 터미널을 흉내냅니다. gitlab-runner는 빌드에서의 모든 출력을 웹 인터페이스로 직접 보냅니다. 그것은 즉, 존재하는 모든 ANSI 색상 코드가 존줍니다.

Windows’ CMD 터미널의 예전 버전(Windows 10 버전 1511 이전)은 ANSI 색상 코드를 지원하지 않습니다. 대신 win32 (ANSI.SYS) 호출을 사용하지만 문자열에서는 포함되지 않습니다. 여러 플랫폼에서 프로그램을 작성할 때 개발자는 통상적으로 기본적으로 ANSI 색상 코드를 사용하고 Windows 시스템에서 실행할 때는 이를 win32 호출로 변환합니다. (예: Colorama).

만약 당신의 프로그램이 위와 같은 작업을 하고 있다면, 빌드에서 ANSI 코드가 문자열에 그대로 남아있도록 그 변환을 비활성화해야 합니다.

더 많은 정보는 GitLab CI YAML docs나 이슈 #332에서 확인할 수 있습니다.

서비스 시작 시 “로그온 실패로 인해 서비스가 시작되지 않음” 오류

Windows에 GitLab Runner 서비스를 설치하고 시작할 때 다음과 같은 오류가 발생할 수 있습니다. 

gitlab-runner install --password WINDOWS_MACHINE_PASSWORD
gitlab-runner start
FATA[0000] Failed to start GitLab Runner: The service did not start due to a logon failure.

이 오류는 서비스를 실행하는 데 사용된 사용자가 SeServiceLogonRight 권한을 가지고 있지 않을 때 발생할 수 있습니다. 이 경우 선택한 사용자에게 이 권한을 추가한 다음 서비스를 다시 시작해야 합니다.

  1. _제어판 > 시스템 및 보안 > 관리 도구_로 이동합니다.
  2. 로컬 보안 정책 도구를 엽니다.
  3. 왼쪽 목록에서 _보안 설정 > 로컬 정책 > 사용 권한 할당_을 선택합니다.
  4. 오른쪽 목록에서 _서비스로 로그온_을 엽니다.
  5. 사용자 또는 그룹 추가… 버튼을 클릭합니다.
  6. 사용자를 추가하고 설정을 적용합니다.

마이크로소프트의 문서에 따르면 이는 Windows Vista, Windows Server 2008, Windows 7, Windows 8.1, Windows Server 2008 R2, Windows Server 2012 R2, Windows Server 2012, 그리고 Windows 8에서 작동해야 합니다.

로컬 보안 정책 도구는 일부 Windows 버전에서 사용할 수 없을 수 있습니다. 예를 들어 각 버전의 “홈 에디션” 변형에서는 사용할 수 없습니다.

서비스 구성에 사용된 사용자에 대해 SeServiceLogonRight를 추가한 후에는 gitlab-runner start 명령이 오류 없이 완료되고 서비스가 올바르게 시작되어야 합니다.

작업이 잘못된 상태로 성공 또는 실패로 표시됨

대부분의 Windows 프로그램은 성공에 대해 exit code 0을 출력합니다. 그러나 일부 프로그램은 종료 코드를 반환하지 않거나 성공에 대해 다른 값을 가질 수 있습니다. 예를 들어 Windows 도구인 robocopy에서는 .gitlab-ci.yml이 robocopy에 의해 출력된 종료 코드로 인해 성공해야 하지만 실패합니다.

위의 경우, script:에 종료 코드를 수동으로 추가해야 합니다. 예를 들어 PowerShell 스크립트를 작성할 수 있습니다. 

$exitCodes = 0,1

robocopy ./source ./dest

if ( $exitCodes.Contains($LastExitCode) ) {
    exit 0
} else {
    exit 1
}

그리고 .gitlab-ci.yml 파일을 다음과 같이 변경합니다. 

test:
  stage: test
  script:
    - New-Item -type Directory -Path ./source
    - New-Item -type Directory -Path ./dest
    - Write-Output "Hello World!" > ./source/file.txt
    - ./robocopyCommand.ps1
  tags:
    - windows

또한 PowerShell 함수를 사용할 때 return와 exit의 차이에 주의해야 합니다. exit 1은 작업을 실패로 표시하지만 return 1은 그렇지 않습니다.

작업이 완료된 것으로 표시되고 중도에 종료된 경우 쿠버네티스 executor 사용

작업 실행을 참조하십시오.

Docker executor: 지원되지 않는 Windows 버전

GitLab Runner는 Windows Server 버전을 확인하여 해당 버전이 지원되는지 확인합니다.

이는 docker info를 실행함으로써 이루어집니다.

아래와 같은 오류로 GitLab Runner가 시작에 실패하고 Windows Server 버전이 명시되지 않은 경우, Docker 버전이 너무 오래되었을 가능성이 높습니다. 

준비 실패: 기본 이미지 감지: 지원되지 않는 Windows 버전: Windows Server Datacenter

이 오류에는 GitLab Runner가 지원하는 Windows Server 버전과 비교되는 Windows Server 버전에 대한 자세한 정보가 포함되어야 합니다. 

지원되지 않는 Windows 버전: Windows Server Datacenter Version (OS Build 18363.720)

Windows Server의 Docker 17.06.2는 docker info 출력에 다음을 반환합니다. 

Operating System: Windows Server Datacenter

이 경우 고쳐야 할 점은 유사한 시기의 더 나중 버전 또는 Windows Server 릴리스와 동일한 버전의 Docker 버전으로 업그레이드하는 것입니다.

Kubernetes executor: 지원되지 않는 Windows 버전

Windows에서 Kubernetes executor는 다음과 같은 오류로 실패할 수 있습니다. 

Using Kubernetes namespace: gitlab-runner
ERROR: 준비 실패: 준비 도우미 이미지: 기본 이미지 감지: 지원되지 않는 Windows 버전:
3초 후 다시 시도될 것입니다 ...
ERROR: 작업 실패 (시스템 오류): 준비 도우미 이미지: 기본 이미지 감지: 지원되지 않는 Windows 버전:

이를 해결하려면 GitLab Runner 구성 파일의 [runners.kubernetes.node_selector] 섹션에 node.kubernetes.io/windows-build nodeSelector를 추가하십시오. 예를 들어: 

   [runners.kubernetes.node_selector]
     "kubernetes.io/arch" = "amd64"
     "kubernetes.io/os" = "windows"
     "node.kubernetes.io/windows-build" = "10.0.17763"

매핑된 네트워크 드라이브를 사용하고 빌드가 올바른 경로를 찾지 못하는 문제

관리자 계정이 아닌 GitLab Runner가 표준 사용자 계정을 사용하고 있는 경우 매핑된 네트워크 드라이브를 사용할 수 없으며, 시스템이 지정한 경로를 찾을 수 없습니다.라는 오류가 발생합니다. 이는 서비스 로그온 세션을 사용하는 것으로 일부 제한 사항이 발생하기 때문입니다. 보안 상의 이유로 일부 자원에 접근하는 제한 사항이 존재합니다. 대신 드라이브의 UNC 경로를 사용하세요.

빌드 컨테이너가 서비스 컨테이너에 연결할 수 없는 문제

Windows 컨테이너에서 서비스를 사용하려면 다음을 수행하세요:

작업이 빌드 디렉토리를 생성하지 못하고 오류가 발생하는 경우

Docker-Windows 실행기를 사용하여 GitLab-Runner를 실행하는 경우 작업이 다음과 같은 오류로 실패할 수 있습니다: 

fatal: cannot chdir to c:/builds/gitlab/test: Permission denied`

이 오류가 발생하는 경우 Docker 엔진이 실행 중인 사용자가 C:\Program Data\Docker에 대한 완전한 권한을 갖도록 확인하세요. 특정 작업에 대해 이 디렉토리에 쓰기 권한이 있어야 하며, 올바른 권한이 없을 경우 작업이 실패합니다.

Windows에서 Docker 엔진 구성에 대해 자세히 알아보기.

Windows Subsystem for Linux (WSL)의 작업 로그에서 빈 줄

기본적으로 Windows Subsystem for Linux (WSL)의 표준 출력은 UTF8로 인코딩되지 않아 작업 로그에서 빈 줄로 표시됩니다. 표준 출력을 표시하려면 WSL_UTF8 환경 변수를 설정하여 WSL에 대해 UTF8 인코딩을 강제로 사용할 수 있습니다. 

job:
  variables:
    WSL_UTF8: "1"