GitLab Runner를 Windows에 설치하기

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

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

공식 사이트에서 설치할 수 있는 Git
Built-in System Account가 아닌 사용자 계정으로 실행하려면 사용자 계정에 대한 비밀번호가 필요합니다.

설치

GitLab Runner 10에서 실행 파일의 이름이 gitlab-runner로 변경되었습니다.

시스템의 어딘가에 폴더를 만드세요. 예: C:\GitLab-Runner.
64-bit 또는 32-bit용 이진 파일을 다운로드하고 생성한 폴더에 넣으세요.
다음 단계는 이진 파일의 이름을 gitlab-runner.exe로 변경했다고 가정합니다(선택 사항).
Bleeding Edge - 다운로드할 다른 태그 릴리스에서 설명한 대로 모든 사용 가능한 버전의 이진 파일을 다운로드할 수 있습니다.
GitLab Runner 디렉터리와 실행 파일에 대한 쓰기 권한을 제한하세요.
이러한 권한을 설정하지 않으면 일반 사용자가 자신의 파일로 실행 파일을 교체하고 상승된 권한으로 임의의 코드를 실행할 수 있습니다.
권한 상승 명령 프롬프트를 실행하세요:
러너 등록하기.
GitLab Runner를 서비스로 설치하고 시작하세요. Built-in System Account(권장)를 사용하거나 사용자 계정을 사용하여 서비스를 실행할 수 있습니다.

Built-in System Account를 사용하여 서비스 실행하기 (위의 1단계에서 생성된 디렉터리에서, 예: C:\GitLab-Runner)
```
cd C:\GitLab-Runner  
.\gitlab-runner.exe install  
.\gitlab-runner.exe start  
```
사용자 계정을 사용하여 서비스 실행하기 (위의 1단계에서 생성된 디렉터리에서, 예: 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 설치 중에 오류가 발생하면 문제 해결 섹션을 참조하세요.
(선택 사항) C:\GitLab-Runner\config.toml에서 러너의 concurrent 값을 업데이트하여 고급 구성 세부정보에서 자세히 설명된 대로 여러 동시 작업을 허용하세요.
또한, 고급 구성 세부정보를 사용하여 Batch 대신 Bash 또는 PowerShell을 사용하도록 셸 실행기를 업데이트할 수 있습니다.

자, 이제 Runner가 설치되었고 실행 중이며 각 시스템 재부팅 후 다시 시작됩니다. 로그는 Windows 이벤트 로그에 저장됩니다.

업그레이드

서비스를 중지합니다. (이전과 같이 관리자 권한 명령 프롬프트를 사용해야 합니다):
```
cd C:\GitLab-Runner
.\gitlab-runner.exe stop
```
64비트 또는 32비트용 바이너리를 다운로드하고 러너의 실행 파일을 교체합니다.

사용 가능한 모든 버전에 대한 바이너리는 Bleeding Edge - download any other tagged release 에 설명되어 있습니다.
서비스를 시작합니다:
```
.\gitlab-runner.exe start
```

제거

관리자 권한 명령 프롬프트 에서:

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

윈도우 문제 해결

FAQ 섹션을 읽어보세요. 이 섹션에서는 GitLab Runner와 관련된 가장 일반적인 문제를 설명합니다.

_계정 이름이 유효하지 않습니다_와 같은 오류가 발생하면 다음을 시도해 보세요:

# 사용자 이름 앞에 \. 추가
.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"

서비스를 시작하는 동안 로그온 실패로 인해 서비스가 시작되지 않았습니다 오류가 발생하면 FAQ에서 확인해 보세요 문제를 해결하는 방법을 확인하세요.

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

내장 시스템 계정에 문제가 있는 경우 내장 시스템 계정으로 서비스를 시작하도록 구성하는 방법 을 읽어보세요.

러너 로그 가져오기

.\gitlab-runner.exe install을 실행하면 gitlab-runner가 Windows 서비스로 설치됩니다. Event Viewer에서 제공자 이름 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가 정의되지 않았습니다. 세션 엔드포인트가 비활성화되었습니다. builds=0...
2/4/2021 6:20:14 AM              1 Information      listen_address가 정의되지 않았습니다. 메트릭 및 디버그 엔드포인트가 비활성화되었습니다. builds=0...
2/4/2021 6:20:14 AM              1 Information      구성 로드됨                                builds=0...
2/4/2021 6:20:14 AM              1 Information      C:\config.toml...에서 다중 러너 시작 중        builds=0...

Windows에서 빌드 중 PathTooLongException이 발생합니다

이는 npm과 같은 도구가 260자 이상의 길이를 가진 디렉토리 구조를 생성할 수 있기 때문에 발생합니다. 문제를 해결하기 위해 채택할 수 있는 두 가지 가능한 수정 방법이 있습니다.

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

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 터미널의 이전 버전(Win10 버전 1511 이전)은 ANSI 색상 코드를 지원하지 않습니다 - 대신 win32 (ANSI.SYS) 호출을 사용하며 이는 표시할 문자열에 포함되지 않습니다. 크로스 플랫폼 프로그램을 작성할 때 개발자는 일반적으로 기본적으로 ANSI 색상 코드를 사용하고 Windows 시스템에서 실행할 때 이를 win32 호출로 변환합니다(예: Colorama).

프로그램이 위와 같은 방식으로 진행되고 있다면, ANSI 코드가 문자열에 남아 있도록 CI 빌드에 대한 변환을 비활성화해야 합니다.

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 권한을 가지고 있지 않은 경우 발생할 수 있습니다. 이 경우, 선택한 사용자에게 이 권한을 추가한 후 서비스를 다시 시작해 보아야 합니다.

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

마이크로소프트 문서에 따르면, 이것은 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

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

unsupported Windows Version: 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 실행기: `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 컨테이너와 서비스 를 사용하려면:

각 작업에 대한 네트워크를 생성하는 네트워킹 모드를 사용하세요.
FF_NETWORK_PER_BUILD 기능 플래그가 활성화되어 있는지 확인하세요.

작업이 빌드 디렉토리를 생성할 수 없고 오류로 실패합니다

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

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 환경 변수를 설정하여 WSL의 UTF8 인코딩을 강제할 수 있습니다.

job:
  variables:
    WSL_UTF8: "1"

GitLab Runner를 Windows에 설치하기

설치

업그레이드

제거

윈도우 문제 해결

러너 로그 가져오기

Windows에서 빌드 중 PathTooLongException이 발생합니다

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

b) PowerShell용 NTFSSecurity 도구 사용

Windows BASH 스크립트를 실행할 수 없습니다. `The system cannot find the batch label specified - buildscript` 에러가 발생합니다.

웹 터미널에서 컬러 출력을 얻으려면 어떻게 해야 하나요?

서비스 시작 시 `The service did not start due to a logon failure` 에러

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

작업이 성공으로 표시되고 Kubernetes 실행기에서 중간에 종료됨

Docker 실행기: `unsupported Windows Version`

Kubernetes 실행기: `unsupported Windows Version`

네트워크 드라이브를 매핑하여 사용하는 중이며 빌드가 올바른 경로를 찾을 수 없습니다

빌드 컨테이너가 서비스 컨테이너에 연결할 수 없습니다

작업이 빌드 디렉토리를 생성할 수 없고 오류로 실패합니다

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

도움말

기능 사용 가능성과 제품 평가판

도움받기

GitLab Runner를 Windows에 설치하기

설치

업그레이드

제거

윈도우 문제 해결

러너 로그 가져오기

Windows에서 빌드 중 PathTooLongException이 발생합니다

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

b) PowerShell용 NTFSSecurity 도구 사용

Windows BASH 스크립트를 실행할 수 없습니다. The system cannot find the batch label specified - buildscript 에러가 발생합니다.

웹 터미널에서 컬러 출력을 얻으려면 어떻게 해야 하나요?

서비스 시작 시 The service did not start due to a logon failure 에러

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

작업이 성공으로 표시되고 Kubernetes 실행기에서 중간에 종료됨

Docker 실행기: unsupported Windows Version

Kubernetes 실행기: unsupported Windows Version

네트워크 드라이브를 매핑하여 사용하는 중이며 빌드가 올바른 경로를 찾을 수 없습니다

빌드 컨테이너가 서비스 컨테이너에 연결할 수 없습니다

작업이 빌드 디렉토리를 생성할 수 없고 오류로 실패합니다

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

도움말

기능 사용 가능성과 제품 평가판

도움받기

Windows BASH 스크립트를 실행할 수 없습니다. `The system cannot find the batch label specified - buildscript` 에러가 발생합니다.

서비스 시작 시 `The service did not start due to a logon failure` 에러

Docker 실행기: `unsupported Windows Version`

Kubernetes 실행기: `unsupported Windows Version`