InfoGrab Docs

Windows에 GitLab Runner 설치

요약

Windows에서 GitLab Runner를 설치하고 실행하려면 다음이 필요합니다: 시스템 어딘가에 폴더를 만듭니다. x86 64비트, ARM 64비트 또는 x86 32비트 바이너리를 다운로드하여 생성한 폴더에 넣습니다.

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

  • 공식 사이트에서 설치할 수 있는 Git
  • 빌트인 시스템 계정 대신 사용자 계정으로 실행하려는 경우 사용자 계정의 비밀번호
  • 문자 인코딩 문제를 방지하기 위해 시스템 로케일을 English (United States)로 설정. 자세한 내용은 이슈 38702를 참조하세요.

설치#

  1. 시스템 어딘가에 폴더를 만듭니다. 예를 들어 C:\GitLab-Runner.

  2. x86 64비트, ARM 64비트 또는 x86 32비트 바이너리를 다운로드하여 생성한 폴더에 넣습니다. 다음은 바이너리 이름을 gitlab-runner.exe로 변경했다고 가정합니다(선택 사항). Bleeding Edge - 다른 태그 릴리스 다운로드에 설명된 대로 모든 사용 가능한 버전의 바이너리를 다운로드할 수 있습니다.

  3. GitLab Runner 디렉터리 및 실행 파일에 대한 Write 권한을 제한하세요. 이 권한을 설정하지 않으면 일반 사용자가 실행 파일을 자신의 것으로 교체하여 승격된 권한으로 임의의 코드를 실행할 수 있습니다.

  4. 관리자 권한 명령 프롬프트를 실행합니다.

  5. 러너를 등록합니다.

  6. GitLab Runner를 서비스로 설치하고 시작합니다. 빌트인 시스템 계정을 사용하거나 사용자 계정을 사용하여 서비스를 실행할 수 있습니다.

    빌트인 시스템 계정을 사용하여 서비스 실행 (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 설치 중 오류가 발생하면 트러블슈팅 섹션을 참조하세요.

  7. (선택 사항) 고급 구성 세부 사항에 설명된 대로 C:\GitLab-Runner\config.toml에서 러너의 concurrent 값을 업데이트하여 여러 동시 잡을 허용합니다. 또한 고급 구성 세부 사항을 사용하여 셸 executor를 Batch 대신 Bash 또는 PowerShell로 업데이트할 수 있습니다.

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

업그레이드#

  1. 서비스를 중지합니다(이전과 같이 관리자 권한 명령 프롬프트가 필요합니다):

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

  2. x86 64비트, ARM 64비트 또는 x86 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 트러블슈팅#

GitLab Runner의 가장 일반적인 문제를 설명하는 FAQ 섹션을 먼저 읽어보세요.

_The account name is invalid_과 같은 오류가 발생하면 다음을 시도하세요:

# Add \. before the username
.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-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/2025 6:20:14 AM              1 Information      [session_server].listen_address not defined, session endpoints disabled  builds=0...
2/4/2025 6:20:14 AM              1 Information      listen_address not defined, metrics & debug endpoints disabled  builds=0...
2/4/2025 6:20:14 AM              1 Information      Configuration loaded                                builds=0...
2/4/2025 6:20:14 AM              1 Information      Starting multi-runner from C:\config.toml...        builds=0...

Windows에서 빌드 중 PathTooLongException 발생#

이 오류는 때때로 260자보다 긴 경로를 가진 디렉터리 구조를 생성하는 npm과 같은 도구에 의해 발생합니다. 문제를 해결하려면 다음 솔루션 중 하나를 사용하세요.

  • core.longpaths가 활성화된 Git 사용:

    Git을 사용하여 디렉터리 구조를 정리하면 문제를 방지할 수 있습니다.

    1. 명령줄에서 git config --system core.longpaths true를 실행합니다.
    2. GitLab CI 프로젝트 설정 페이지에서 git fetch를 사용하도록 프로젝트를 설정합니다.

  • PowerShell용 NTFSSecurity 도구 사용:

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

GitLab Runner 16.9.1에서 도입된 회귀가 GitLab Runner 17.10.0에서 수정되었습니다. 회귀가 있는 GitLab Runner 버전을 사용하려는 경우 다음 해결 방법 중 하나를 사용하세요:

  • pre_get_sources_script를 사용하여 Git 시스템 수준 설정을 다시 활성화합니다(Git_CONFIG_NOSYSTEM 설정 해제). 이 작업은 Windows에서 기본적으로 core.longpaths를 활성화합니다.

    build:
  hooks:
    pre_get_sources_script:
      - $env:GIT_CONFIG_NOSYSTEM=''

  • 커스텀 GitLab-runner-helper 이미지 빌드:

    FROM registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v17.8.3-servercore21H2
ENV GIT_CONFIG_NOSYSTEM=

Windows 배치 스크립트 오류: The system cannot find the batch label specified - buildscript#

.gitlab-ci.yml의 Batch 파일 라인에 call을 앞에 붙여 call C:\path\to\test.bat처럼 보이도록 해야 합니다. 예를 들어:

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

자세한 내용은 이슈 1025를 참조하세요.

웹 터미널에서 색상 출력을 얻으려면 어떻게 해야 합니까?#

간단한 답변:

프로그램 출력에 ANSI 색상 코드가 있는지 확인하세요. 텍스트 형식 지정 목적으로 UNIX ANSI 터미널 에뮬레이터에서 실행 중이라고 가정하세요(웹 인터페이스 출력이기 때문입니다).

자세한 답변:

GitLab CI의 웹 인터페이스는 UNIX ANSI 터미널을 (적어도 부분적으로) 에뮬레이션합니다. gitlab-runner는 빌드의 모든 출력을 직접 웹 인터페이스로 파이프합니다. 이는 존재하는 모든 ANSI 색상 코드가 적용됨을 의미합니다.

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

프로그램이 위와 같은 작업을 하는 경우, ANSI 코드가 문자열에 남아 있도록 CI 빌드에서 해당 변환을 비활성화해야 합니다.

자세한 내용은 PowerShell을 사용한 예시와 이슈 332에 대한 GitLab CI YAML 문서를 참조하세요.

오류: 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 executor를 사용하여 잡이 성공으로 표시되고 중간에 종료됨#

자세한 내용은 잡 실행을 참조하세요.

Docker executor: 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 버전에 대한 자세한 정보가 포함되어야 하며, 이는 GitLab Runner가 지원하는 버전과 비교됩니다.

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 executor: unsupported Windows Version#

Windows의 Kubernetes executor는 다음 오류로 실패할 수 있습니다:

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 노드 셀렉터를 추가하세요. 예를 들어:

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

매핑된 네트워크 드라이브를 사용 중인데 빌드에서 올바른 경로를 찾을 수 없음#

GitLab Runner가 관리자 계정 대신 표준 사용자 계정으로 실행될 때 매핑된 네트워크 드라이브에 액세스할 수 없습니다. 매핑된 네트워크 드라이브를 사용하려고 하면 The system cannot find the path specified. 오류가 발생합니다. 이 오류는 서비스 로그온 세션이 리소스에 액세스할 때 보안 제한이 있기 때문에 발생합니다. 대신 드라이브의 UNC 경로를 사용하세요.

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

Windows 컨테이너에서 서비스를 사용하려면:

잡이 빌드 디렉터리를 만들 수 없어 오류와 함께 실패함#

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

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로 인코딩되지 않으며 잡 로그에 빈 줄로 표시됩니다. STDOUT 출력을 표시하려면 WSL_UTF8 환경 변수를 설정하여 WSL에 UTF8 인코딩을 강제할 수 있습니다.

job:
  variables:
    WSL_UTF8: "1"

디스플레이 해상도가 1024x768로 제한됨#

GitLab Runner를 시스템 서비스로 사용하여 Windows에서 CI/CD 잡을 실행할 때 디스플레이 해상도가 1024x768로 제한됩니다. 이 문제는 Windows Session 0 격리로 인해 발생합니다. 자세한 내용은 Session 0 격리를 참조하세요.

세션과 디스플레이 해상도를 확인하려면 잡에서 다음 PowerShell 스크립트를 실행하세요:

echo "Current session:"
[System.Diagnostics.Process]::GetCurrentProcess().SessionId

Add-Type -AssemblyName System.Windows.Forms
[System.Windows.Forms.Screen]::AllScreens

격리된 세션 0에서 실행 시 스크립트 출력 예시:

Current session:
0
BitsPerPixel : 0
Bounds       : {X=0,Y=0,Width=1024,Height=768}
DeviceName   : WinDisc
Primary      : True
WorkingArea  : {X=0,Y=0,Width=1024,Height=768}

Windows에 GitLab Runner 설치

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기
요약

Windows에서 GitLab Runner를 설치하고 실행하려면 다음이 필요합니다: 시스템 어딘가에 폴더를 만듭니다. x86 64비트, ARM 64비트 또는 x86 32비트 바이너리를 다운로드하여 생성한 폴더에 넣습니다.

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

  • 공식 사이트에서 설치할 수 있는 Git
  • 빌트인 시스템 계정 대신 사용자 계정으로 실행하려는 경우 사용자 계정의 비밀번호
  • 문자 인코딩 문제를 방지하기 위해 시스템 로케일을 English (United States)로 설정. 자세한 내용은 이슈 38702를 참조하세요.

설치#

  1. 시스템 어딘가에 폴더를 만듭니다. 예를 들어 C:\GitLab-Runner.

  2. x86 64비트, ARM 64비트 또는 x86 32비트 바이너리를 다운로드하여 생성한 폴더에 넣습니다. 다음은 바이너리 이름을 gitlab-runner.exe로 변경했다고 가정합니다(선택 사항). Bleeding Edge - 다른 태그 릴리스 다운로드에 설명된 대로 모든 사용 가능한 버전의 바이너리를 다운로드할 수 있습니다.

  3. GitLab Runner 디렉터리 및 실행 파일에 대한 Write 권한을 제한하세요. 이 권한을 설정하지 않으면 일반 사용자가 실행 파일을 자신의 것으로 교체하여 승격된 권한으로 임의의 코드를 실행할 수 있습니다.

  4. 관리자 권한 명령 프롬프트를 실행합니다.

  5. 러너를 등록합니다.

  6. GitLab Runner를 서비스로 설치하고 시작합니다. 빌트인 시스템 계정을 사용하거나 사용자 계정을 사용하여 서비스를 실행할 수 있습니다.

    빌트인 시스템 계정을 사용하여 서비스 실행 (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 설치 중 오류가 발생하면 트러블슈팅 섹션을 참조하세요.

  7. (선택 사항) 고급 구성 세부 사항에 설명된 대로 C:\GitLab-Runner\config.toml에서 러너의 concurrent 값을 업데이트하여 여러 동시 잡을 허용합니다. 또한 고급 구성 세부 사항을 사용하여 셸 executor를 Batch 대신 Bash 또는 PowerShell로 업데이트할 수 있습니다.

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

업그레이드#

  1. 서비스를 중지합니다(이전과 같이 관리자 권한 명령 프롬프트가 필요합니다):

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

  2. x86 64비트, ARM 64비트 또는 x86 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 트러블슈팅#

GitLab Runner의 가장 일반적인 문제를 설명하는 FAQ 섹션을 먼저 읽어보세요.

_The account name is invalid_과 같은 오류가 발생하면 다음을 시도하세요:

# Add \. before the username
.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-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/2025 6:20:14 AM              1 Information      [session_server].listen_address not defined, session endpoints disabled  builds=0...
2/4/2025 6:20:14 AM              1 Information      listen_address not defined, metrics & debug endpoints disabled  builds=0...
2/4/2025 6:20:14 AM              1 Information      Configuration loaded                                builds=0...
2/4/2025 6:20:14 AM              1 Information      Starting multi-runner from C:\config.toml...        builds=0...

Windows에서 빌드 중 PathTooLongException 발생#

이 오류는 때때로 260자보다 긴 경로를 가진 디렉터리 구조를 생성하는 npm과 같은 도구에 의해 발생합니다. 문제를 해결하려면 다음 솔루션 중 하나를 사용하세요.

  • core.longpaths가 활성화된 Git 사용:

    Git을 사용하여 디렉터리 구조를 정리하면 문제를 방지할 수 있습니다.

    1. 명령줄에서 git config --system core.longpaths true를 실행합니다.
    2. GitLab CI 프로젝트 설정 페이지에서 git fetch를 사용하도록 프로젝트를 설정합니다.

  • PowerShell용 NTFSSecurity 도구 사용:

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

GitLab Runner 16.9.1에서 도입된 회귀가 GitLab Runner 17.10.0에서 수정되었습니다. 회귀가 있는 GitLab Runner 버전을 사용하려는 경우 다음 해결 방법 중 하나를 사용하세요:

  • pre_get_sources_script를 사용하여 Git 시스템 수준 설정을 다시 활성화합니다(Git_CONFIG_NOSYSTEM 설정 해제). 이 작업은 Windows에서 기본적으로 core.longpaths를 활성화합니다.

    build:
  hooks:
    pre_get_sources_script:
      - $env:GIT_CONFIG_NOSYSTEM=''

  • 커스텀 GitLab-runner-helper 이미지 빌드:

    FROM registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v17.8.3-servercore21H2
ENV GIT_CONFIG_NOSYSTEM=

Windows 배치 스크립트 오류: The system cannot find the batch label specified - buildscript#

.gitlab-ci.yml의 Batch 파일 라인에 call을 앞에 붙여 call C:\path\to\test.bat처럼 보이도록 해야 합니다. 예를 들어:

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

자세한 내용은 이슈 1025를 참조하세요.

웹 터미널에서 색상 출력을 얻으려면 어떻게 해야 합니까?#

간단한 답변:

프로그램 출력에 ANSI 색상 코드가 있는지 확인하세요. 텍스트 형식 지정 목적으로 UNIX ANSI 터미널 에뮬레이터에서 실행 중이라고 가정하세요(웹 인터페이스 출력이기 때문입니다).

자세한 답변:

GitLab CI의 웹 인터페이스는 UNIX ANSI 터미널을 (적어도 부분적으로) 에뮬레이션합니다. gitlab-runner는 빌드의 모든 출력을 직접 웹 인터페이스로 파이프합니다. 이는 존재하는 모든 ANSI 색상 코드가 적용됨을 의미합니다.

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

프로그램이 위와 같은 작업을 하는 경우, ANSI 코드가 문자열에 남아 있도록 CI 빌드에서 해당 변환을 비활성화해야 합니다.

자세한 내용은 PowerShell을 사용한 예시와 이슈 332에 대한 GitLab CI YAML 문서를 참조하세요.

오류: 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 executor를 사용하여 잡이 성공으로 표시되고 중간에 종료됨#

자세한 내용은 잡 실행을 참조하세요.

Docker executor: 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 버전에 대한 자세한 정보가 포함되어야 하며, 이는 GitLab Runner가 지원하는 버전과 비교됩니다.

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 executor: unsupported Windows Version#

Windows의 Kubernetes executor는 다음 오류로 실패할 수 있습니다:

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 노드 셀렉터를 추가하세요. 예를 들어:

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

매핑된 네트워크 드라이브를 사용 중인데 빌드에서 올바른 경로를 찾을 수 없음#

GitLab Runner가 관리자 계정 대신 표준 사용자 계정으로 실행될 때 매핑된 네트워크 드라이브에 액세스할 수 없습니다. 매핑된 네트워크 드라이브를 사용하려고 하면 The system cannot find the path specified. 오류가 발생합니다. 이 오류는 서비스 로그온 세션이 리소스에 액세스할 때 보안 제한이 있기 때문에 발생합니다. 대신 드라이브의 UNC 경로를 사용하세요.

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

Windows 컨테이너에서 서비스를 사용하려면:

잡이 빌드 디렉터리를 만들 수 없어 오류와 함께 실패함#

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

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로 인코딩되지 않으며 잡 로그에 빈 줄로 표시됩니다. STDOUT 출력을 표시하려면 WSL_UTF8 환경 변수를 설정하여 WSL에 UTF8 인코딩을 강제할 수 있습니다.

job:
  variables:
    WSL_UTF8: "1"

디스플레이 해상도가 1024x768로 제한됨#

GitLab Runner를 시스템 서비스로 사용하여 Windows에서 CI/CD 잡을 실행할 때 디스플레이 해상도가 1024x768로 제한됩니다. 이 문제는 Windows Session 0 격리로 인해 발생합니다. 자세한 내용은 Session 0 격리를 참조하세요.

세션과 디스플레이 해상도를 확인하려면 잡에서 다음 PowerShell 스크립트를 실행하세요:

echo "Current session:"
[System.Diagnostics.Process]::GetCurrentProcess().SessionId

Add-Type -AssemblyName System.Windows.Forms
[System.Windows.Forms.Screen]::AllScreens

격리된 세션 0에서 실행 시 스크립트 출력 예시:

Current session:
0
BitsPerPixel : 0
Bounds       : {X=0,Y=0,Width=1024,Height=768}
DeviceName   : WinDisc
Primary      : True
WorkingArea  : {X=0,Y=0,Width=1024,Height=768}