Windows에서 GitLab Runner 설치

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

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

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

설치

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

시스템의 어딘가에 폴더를 만듭니다. 예: C:\GitLab-Runner.
64비트 또는 32비트용 실행 파일을 다운로드하여 만든 폴더에 넣습니다. 다음은 실행 파일의 이름을 gitlab-runner.exe(선택 사항)로 변경했다고 가정합니다. 다른 버전에 대한 실행 파일을 다운로드할 수 있습니다. 자세한 내용은 Bleeding Edge - 다른 태그가 지정된 릴리스 다운로드를 참조하세요.
GitLab Runner 디렉토리 및 실행 파일에 쓰기 권한을 제한해야 합니다. 이러한 권한을 설정하지 않으면 일반 사용자가 자신의 실행 파일로 대체하고 상승된 권한으로 임의의 코드를 실행할 수 있습니다.
상승된 명령 프롬프트에서 다음을 실행합니다.
런너 등록.
GitLab Runner를 서비스로 설치하고 시작합니다. 서비스를 실행할 수 있도록 Built-in System Account(권장) 또는 사용자 계정을 사용할 수 있습니다.
Built-in System Account를 사용하여 서비스 실행하기(위에서 만든 디렉토리 내, 예: 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 설치 중 오류가 발생한 경우 문제 해결 섹션을 참조하세요.
(선택 사항) C:\GitLab-Runner\config.toml의 러너의 concurrent 값을 업데이트하여 고급 구성 세부 정보에 설명된 대로 여러 작업을 병행할 수 있습니다. 또한, 고급 구성 세부 정보를 사용하여 쉘 실행기를 배치가 아닌 Bash 또는 PowerShell로 업데이트할 수 있습니다.

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

업그레이드

서비스를 중지합니다 (이전과 동일하게 상승된 명령 프롬프트가 필요합니다).
```
cd C:\GitLab-Runner
.\gitlab-runner.exe stop
```
64비트 또는 32비트용 실행 파일을 다운로드하여 러너의 실행 파일을 바꿉니다. 다른 버전에 대한 실행 파일을 다운로드할 수 있습니다. 자세한 내용은 Bleeding Edge - 다른 태그가 지정된 릴리스 다운로드를 참조하세요.
서비스를 시작합니다.
```
.\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 섹션을 반드시 읽어보세요.

계정 이름이 유효하지 않다는 오류가 발생하는 경우:

# 사용자 이름 앞에 \.을 추가합니다.
.\gitlab-runner.exe install --user ".\사용자명" --password "암호입력"

서비스를 시작하는 중 _로그온 실패로 서비스를 시작하지 못했습니다_라는 오류가 발생하는 경우, 문제를 해결하는 방법에 대해 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 발생

이는 때때로 260자 이상의 경로를 생성할 수 있는 npm과 같은 도구에 의해 발생합니다. 문제를 해결하기 위해 채택할 수 있는 두 가지 수정 방법이 있습니다.

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

추가 정보는 issue #1025에서 찾을 수 있습니다.

웹 터미널에서 색상이 있는 출력을 받으려면 어떻게 해야 하나요?

간단한 답변:

프로그램의 출력에 ANSI 색상 코드가 있는지 확인하세요. 텍스트 서식을 위해 UNIX ANSI 터미널 에뮬레이터에서 실행 중이라고 가정하십시오 (왜냐하면 웹UI의 출력이 그렇기 때문입니다).

구체적인 답변:

GitLab CI의 웹 인터페이스는 UNIX ANSI 터미널을 흉내냅니다 (적어도 일부분). gitlab-runner는 빌드에서의 모든 출력을 웹 인터페이스로 직접 전달합니다. 이는 존재하는 모든 ANSI 색상 코드가 존중받게 됨을 의미합니다.

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

만약 프로그램이 위와 같은 동작을 한다면 CI 빌드를 위해 이러한 변환을 비활성화해야 합니다.

추가 정보는 GitLab CI YAML docs와 issue #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 권한을 가지고 있지 않을 때 발생할 수 있습니다. 이 경우 선택한 사용자에게 이 권한을 추가한 다음 서비스를 다시 시작해야 합니다.

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

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은 표시하지 않습니다.

쿠버네티스 실행기를 사용하여 작업이 성공으로 표시되었지만 중간에 종료됨

작업 실행을 참조하세요.

Docker 실행기: `지원되지 않는 Windows 버전`

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

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

만약 다음과 같은 오류로 GitLab Runner가 시작하지 못하는 경우, 그리고 Windows Server 버전이 명시되지 않은 경우, 그것은 Docker 버전이 너무 오래되었을 가능성이 높습니다.

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

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

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

Windows Server의 Docker 17.06.2는 다음과 같은 출력을 반환합니다.

Operating System: Windows Server Datacenter

이 경우에는 유사한 시기의 Docker 버전을 업그레이드하거나 Windows Server 릴리스보다 나중 버전으로 업그레이드해야 합니다.

쿠버네티스 실행기: `지원되지 않는 Windows 버전`

Windows에서 쿠버네티스 실행기는 다음과 같은 오류로 실패할 수 있습니다:

Kubernetes 네임스페이스 사용: gitlab-runner
오류: 준비 실패: 도우미 이미지 준비: 기본 이미지 감지: 지원되지 않는 Windows 버전:
3초 후에 재시도됩니다 ...
오류: 작업 실패 (시스템 실패): 도우미 이미지 준비: 기본 이미지 감지: 지원되지 않는 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 컨테이너에서 서비스를 사용하려면:

각 작업을 위한 네트워크를 만드는 네트워킹 모드를 사용합니다.
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 Engine 구성에 대해 자세히 알아보기.

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

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

job:
  variables:
    WSL_UTF8: "1"

Windows에서 GitLab Runner 설치

설치

업그레이드

제거

Windows 문제 해결

러너 로그 가져오기

Windows 빌드 중에 PathTooLongException 발생

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

b) PowerShell용 NTFSSecurity 도구 사용

Windows BASH 스크립트를 실행할 수 없음; ‘The system cannot find the batch label specified - buildscript’ 오류 발생

웹 터미널에서 색상이 있는 출력을 받으려면 어떻게 해야 하나요?

서비스 시작 시 ‘로그온 실패로 인해 서비스가 시작되지 않았습니다’ 오류

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

쿠버네티스 실행기를 사용하여 작업이 성공으로 표시되었지만 중간에 종료됨

Docker 실행기: `지원되지 않는 Windows 버전`

쿠버네티스 실행기: `지원되지 않는 Windows 버전`

매핑된 네트워크 드라이브를 사용하고 내 빌드가 올바른 경로를 찾을 수 없음

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

작업이 빌드 디렉토리를 생성하지 못하고 오류와 함께 실패함

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

도움말

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

도움받기

Windows에서 GitLab Runner 설치

설치

업그레이드

제거

Windows 문제 해결

러너 로그 가져오기

Windows 빌드 중에 PathTooLongException 발생

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

b) PowerShell용 NTFSSecurity 도구 사용

Windows BASH 스크립트를 실행할 수 없음; ‘The system cannot find the batch label specified - buildscript’ 오류 발생

웹 터미널에서 색상이 있는 출력을 받으려면 어떻게 해야 하나요?

서비스 시작 시 ‘로그온 실패로 인해 서비스가 시작되지 않았습니다’ 오류

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

쿠버네티스 실행기를 사용하여 작업이 성공으로 표시되었지만 중간에 종료됨

Docker 실행기: 지원되지 않는 Windows 버전

쿠버네티스 실행기: 지원되지 않는 Windows 버전

매핑된 네트워크 드라이브를 사용하고 내 빌드가 올바른 경로를 찾을 수 없음

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

작업이 빌드 디렉토리를 생성하지 못하고 오류와 함께 실패함

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

도움말

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

도움받기

Docker 실행기: `지원되지 않는 Windows 버전`

쿠버네티스 실행기: `지원되지 않는 Windows 버전`