Windows에서 GitLab Runner 설치

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

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

  • 공식 사이트에서 설치할 수 있는 Git
  • 내장 시스템 계정 대신 사용자 계정에서 실행하려면 사용자 계정의 암호가 필요합니다.

설치

caution
GitLab Runner 10부터 실행 파일이 gitlab-runner로 이름이 변경되었습니다.
  1. 시스템의 원하는 위치에 폴더를 생성합니다. 예: C:\GitLab-Runner.
  2. 64비트 또는 32비트용 바이너리를 다운로드하여 생성한 폴더에 넣습니다. 다음은 바이너리의 이름을 gitlab-runner.exe로 변경했다고 가정합니다 (선택 사항). 블리딩 에지 - 다른 태그된 릴리스 다운로드에 설명된대로 모든 사용 가능한 버전의 바이너리를 다운로드할 수 있습니다.
  3. GitLab Runner 디렉터리 및 실행 파일에 쓰기 권한을 제한해야 합니다. 이러한 권한을 설정하지 않으면 일반 사용자가 실행 파일을 자신의 것으로 대체하고 상승된 권한으로 임의의 코드를 실행할 수 있습니다.
  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 사용자명 --password 암호입력
.\gitlab-runner.exe start

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

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

여기! Runner가 설치되어 실행되며, 시스템 재부팅 후에도 다시 시작될 것입니다. 로그는 Windows 이벤트 로그에 저장됩니다.

업그레이드

  1. 서비스를 중지합니다 (이전과 동일한 상승된 명령 프롬프트가 필요합니다): 

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

  2. 64비트 또는 32비트용 바이너리를 다운로드하여 러너의 실행 파일을 교체합니다. 블리딩 에지 - 다른 태그된 릴리스 다운로드에 설명된대로 모든 사용 가능한 버전의 바이너리를 다운로드할 수 있습니다.

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

    .\gitlab-runner.exe start

제거

상승된 명령 프롬프트에서: 

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

Windows 문제 해결

GitLab Runner와 함께 발생할 수 있는 일반적인 문제에 대해 설명한 FAQ 섹션을 반드시 읽으십시오.

_The account name is invalid_와 같은 오류가 발생하면 사용자 이름 앞에 .\를 추가해보십시오: 

.\gitlab-runner.exe install --user ".\사용자명" --password "암호"

서비스를 시작하는 동안 The service did not start due to a logon failure 오류가 발생하면 문제를 해결하는 방법을 확인하려면 FAQ를 참조하십시오.

Windows 암호가 없는 경우 GitLab Runner 서비스가 시작되지 않지만 내장 시스템 계정을 사용할 수 있습니다.

내장 시스템 계정에 문제가 있는 경우 Microsoft의 지원 웹사이트에서 내장 시스템 계정으로 시작 구성을 참조하십시오.

러너 로그 가져오기

.\gitlab-runner.exe install을 실행하면 gitlab-runner을 Windows 서비스로 설치합니다. 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에 배치 파일 라인 앞에 call을 붙여야 합니다. 따라서 이렇게 보여야 합니다. call C:\path\to\test.bat: 

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 문서에서 PowerShell 사용 예시와 더 많은 정보는 이슈 #332에서 확인할 수 있습니다.

서비스 시작 시 The service did not start due to a logon failure 오류

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. 사용자를 추가한 다음 설정을 적용합니다.

Microsoft 문서에 따르면, 이 방법은 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에 의해 출력된 종료 코드 때문에 성공해야 할 작업이 실패합니다: 

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

위의 경우, 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은 표시하지 않습니다.

작업이 잘못된 성공으로 표시됨 또는 Kubernetes 실행자를 통해 중간에 종료된 경우

작업 실행를 참조하세요.

Docker 실행자: unsupported Windows Version

GitLab Runner는 Windows Server 버전을 확인하여 지원하는지 여부를 검증합니다.

이를 위해 docker info 명령을 실행합니다.

다음과 같은 오류로 GitLab Runner가 시작에 실패하면서 Windows Server 버전이 지정되지 않은 경우, Docker 버전이 너무 오래됐기 때문일 가능성이 있습니다. 

Preparation failed: detecting base image: unsupported Windows Version: Windows Server Datacenter

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

unsupported Windows Version: Windows Server Datacenter Version (OS Build 18363.720)

Windows Server의 출력에는 다음 내용이 포함돼야 합니다. 

Operating System: Windows Server Datacenter

이 경우 수정 방법은 유사한 시대 이상 또는 이후의 Docker 버전을 업그레이드하는 것입니다.

Kubernetes 실행자: unsupported Windows Version

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

Using Kubernetes namespace: gitlab-runner
ERROR: Preparation failed: prepare helper image: detecting base image: unsupported Windows Version:
Will be retried in 3s ...
ERROR: Job failed (system failure): prepare helper image: detecting base image: unsupported Windows Version:

이를 수정하려면 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 컨테이너에 서비스를 사용하려면:

작업이 빌드 디렉터리를 생성하지 못하고 오류로 실패하는 문제

GitLab-Runner를 Docker-Windows executor로 사용할 때, 작업이 다음과 같은 오류로 실패할 수 있습니다: 

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

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

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

Windows Subsystem for Linux (WSL)의 표준 출력 (STDOUT) 출력에 대한 빈 줄

기본적으로 Windows Subsystem for Linux (WSL)의 표준 출력 (STDOUT)은 UTF8로 인코딩되지 않으며 작업 로그에서 빈 줄로 표시됩니다. STDOUT 출력을 표시하려면 WSL에 대해 UTF8 인코딩을 강제로 설정하여야 합니다. 

job:
  variables:
    WSL_UTF8: "1"