이 섹션은 GitLab Runner 문제 해결에 도움이 됩니다.

일반적인 문제 해결 팁#

로그 보기#

GitLab Runner 서비스는 syslog에 로그를 전송합니다. 로그를 보려면 배포판 문서를 참조하세요. 배포판에 journalctl 명령이 포함되어 있으면 다음 명령으로 로그를 볼 수 있습니다:

journalctl --unit=gitlab-runner.service -n 100 --no-pager
docker logs gitlab-runner-container # Docker
kubectl logs gitlab-runner-pod # Kubernetes

서비스 재시작#

systemctl restart gitlab-runner.service

Docker 머신 보기#

sudo docker-machine ls
sudo su - && docker-machine ls

모든 Docker 머신 삭제#

docker-machine rm $(docker-machine ls -q)

config.toml에 변경 사항 적용#

systemctl restart gitlab-runner.service
docker-machine rm $(docker-machine ls -q) # Docker machine
journalctl --unit=gitlab-runner.service -f # 잠재적 오류를 확인하기 위해 로그 tail

GitLab과 GitLab Runner 버전 확인#

GitLab은 하위 호환성 보장을 목표로 합니다. 그러나 첫 번째 문제 해결 단계로 GitLab Runner의 버전이 GitLab 버전과 동일한지 확인해야 합니다.

coordinator란 무엇인가요?#

coordinator는 작업이 요청되는 GitLab 설치입니다.

즉, 러너는 coordinator(GitLab API를 통한 GitLab 설치)에서 작업을 요청하는 격리된 에이전트입니다.

Windows에서 서비스로 실행할 때 로그는 어디에 저장되나요?#

• GitLab Runner가 Windows에서 서비스로 실행 중이면 시스템 이벤트 로그를 생성합니다. 이를 보려면 이벤트 뷰어를 엽니다(실행 메뉴에서 eventvwr.msc를 입력하거나 "이벤트 뷰어"를 검색). 그런 다음 Windows 로그 > 응용 프로그램으로 이동합니다. 러너 로그의 원본은 gitlab-runner입니다. Windows Server Core를 사용하는 경우 이 PowerShell 명령을 실행하여 최근 로그 항목 20개를 가져옵니다: get-eventlog Application -Source gitlab-runner -Newest 20 | format-table -wrap -auto.

디버그 로깅 모드 활성화#

명령줄에서#

터미널에서 root로 로그인하여 다음을 실행합니다.

gitlab-runner stop
gitlab-runner --debug run

GitLab Runner config.toml에서#

log_level 설정을 debug로 설정하여 config.toml의 글로벌 섹션에서 디버그 로깅을 활성화할 수 있습니다. config.toml의 맨 위에, concurrent 줄 앞이나 뒤에 다음 줄을 추가하세요:

log_level = "debug"

Helm Chart에서#

GitLab Runner가 GitLab Runner Helm Chart를 사용하여 Kubernetes 클러스터에 설치된 경우, 디버그 로깅을 활성화하려면 values.yaml 사용자 정의에서 logLevel 옵션을 설정합니다:

## GitLab Runner 로깅 수준을 구성합니다. 사용 가능한 값: debug, info, warn, error, fatal, panic
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration/#the-global-section
##
logLevel: debug

GitLab Runner 로그의 상관 관계 ID#

GitLab Runner는 GitLab과의 상호 작용을 추적하기 위해 각 API 요청에 대한 상관 관계 ID를 생성합니다.

GitLab의 API 응답이 X-Request-Id 헤더에 상관 관계 ID를 포함하는 경우, 해당 값(일반적으로 ULID 형식)이 로그에 사용됩니다. 응답에 상관 관계 ID가 포함되지 않으면, GitLab Runner는 요청을 위해 생성한 UUID(대시 없는 소문자 16진수 형식)를 사용합니다. 폴백 상관 관계 ID는 요청이 GitLab Workhorse에 도달하지 못했음을 나타냅니다. 이슈는 중간 홉(WAF, CDN, 로드 밸런서, 프록시 등)에서 발생했을 가능성이 높습니다.

상관 관계 ID를 사용하여 컴포넌트 간 로그 항목을 일치시키고 요청 흐름을 추적할 수 있습니다. GitLab Runner 로그에서 correlation_id 필드와 GitLab 서버 로그의 해당 ID를 검색하여 이벤트를 연관시킵니다.

예시 로그 항목:

# 유효한 상관 관계 ID (GitLab API 응답의 ULID 형식)
Appending trace to coordinator...ok correlation_id=01KKDQ7P6TRW7Z6P2PWG5808EK job=101162491 status=202 Accepted

# 폴백 상관 관계 ID (러너가 생성한 대시 없는 소문자 16진수 UUID)
WARNING: Appending trace to coordinator... job failed correlation_id=21fe32aee0e146c194640b075c95ec7c job=101162868 status=403 Forbidden

Docker 실행기 러너에 대한 DNS 구성#

GitLab Runner를 Docker 실행기로 구성하면 호스트 러너 데몬이 액세스할 수 있어도 Docker 컨테이너가 GitLab에 액세스하지 못할 수 있습니다. 이는 호스트에 DNS가 구성되어 있지만 해당 구성이 컨테이너에 전달되지 않을 때 발생할 수 있습니다.

예시:

GitLab 서비스와 GitLab Runner가 두 가지 방법(예: 인터넷과 VPN을 통해)으로 브리지된 두 개의 다른 네트워크에 있습니다. 러너의 라우팅 메커니즘이 VPN을 통한 DNS 서비스 대신 기본 인터넷 서비스를 통해 DNS를 쿼리할 수 있습니다. 이 구성은 다음과 같은 메시지를 발생시킵니다:

Created fresh repository.
++ echo 'Created fresh repository.'
++ git -c 'http.userAgent=gitlab-runner 16.5.0 linux/amd64' fetch origin +da39a3ee5e6b4b0d3255bfef95601890afd80709:refs/pipelines/435345 +refs/heads/master:refs/remotes/origin/master --depth 50 --prune --quiet
fatal: Authentication failed for 'https://gitlab.example.com/group/example-project.git/'

이 경우 인증 실패는 인터넷과 GitLab 서비스 사이의 서비스에 의해 발생합니다. 이 서비스는 별도의 자격 증명을 사용하며, 러너가 VPN을 통해 DNS 서비스를 사용한다면 우회할 수 있습니다.

러너의 config.toml 파일의 [runners.docker] 섹션에서 dns 구성을 사용하여 Docker가 사용할 DNS 서버를 지정할 수 있습니다.

dns = ["192.168.xxx.xxx","192.168.xxx.xxx"]

x509: certificate signed by unknown authority 오류#

자세한 내용은 자체 서명 인증서를 참조하세요.

/var/run/docker.sock에 액세스할 때 Permission Denied 오류#

Docker 실행기를 사용하려는 경우, 서버에 설치된 Docker Engine에 연결하고 있다면 Permission Denied 오류가 표시될 수 있습니다. 가장 가능성 있는 원인은 시스템이 SELinux(CentOS, Fedora, RHEL에서 기본적으로 활성화됨)를 사용하기 때문입니다. 가능한 거부 사항에 대해 시스템의 SELinux 정책을 확인하세요.

Docker-machine 오류: Unable to query docker version: Cannot connect to the docker engine endpoint.#

이 오류는 머신 프로비저닝과 관련이 있으며 다음 이유로 인해 발생할 수 있습니다:

• TLS 실패가 있습니다. docker-machine이 설치될 때 일부 인증서가 유효하지 않을 수 있습니다. 이 이슈를 해결하려면 인증서를 제거하고 러너를 재시작합니다:

  sudo su -
  rm -r /root/.docker/machine/certs/*
  service gitlab-runner restart
  

  러너가 재시작된 후 인증서가 비어 있음을 등록하고 다시 만듭니다.

• 호스트 이름이 프로비저닝된 머신에서 지원되는 길이보다 깁니다. 예를 들어 Ubuntu 머신은 HOST_NAME_MAX에 대해 64자 제한이 있습니다. 호스트 이름은 docker-machine ls로 보고됩니다. 러너 구성에서 MachineName을 확인하고 필요하면 호스트 이름 길이를 줄이세요.

dialing environment connection: ssh: rejected: connect failed (open failed)#

이 오류는 Docker 자동 스케일러가 SSH를 통해 연결이 터널링될 때 대상 시스템의 Docker 데몬에 도달할 수 없을 때 발생합니다. 대상 시스템에 SSH로 접속할 수 있고 docker info와 같은 Docker 명령을 성공적으로 실행할 수 있는지 확인하세요.

자동 스케일링 러너에 AWS 인스턴스 프로파일 추가#

AWS IAM 역할을 생성한 후 IAM 콘솔에서 역할에는 Role ARN과 Instance Profile ARNs가 있습니다. Role Name이 아닌 Instance Profile 이름을 사용해야 합니다.

[runners.machine] 섹션에 다음 값을 추가합니다: "amazonec2-iam-instance-profile=<instance-profile-name>",

Docker 실행기가 Java 프로젝트를 빌드할 때 타임아웃 발생#

이는 aufs 스토리지 드라이버 문제 때문에 발생할 가능성이 가장 높습니다: 컨테이너 내부에서 Java 프로세스가 멈춤. 가장 좋은 해결책은 스토리지 드라이버를 OverlayFS(더 빠름) 또는 DeviceMapper(더 느림)로 변경하는 것입니다.

Docker 구성 및 실행에 관한 이 문서 또는 systemd로 제어 및 구성에 관한 이 문서를 참조하세요.

아티팩트 업로드 시 411 오류 발생#

이는 GitLab Runner가 조기 버전의 NGINX에서 손상된 Transfer-Encoding: chunked를 사용하기 때문에 발생합니다(https://serverfault.com/questions/164220/is-there-a-way-to-avoid-nginx-411-content-length-required-errors).

NGINX를 최신 버전으로 업그레이드하세요. 자세한 내용은 이 이슈를 참조하세요: https://gitlab.com/gitlab-org/gitlab-runner/-/issues/1031

다른 아티팩트 업로드 오류가 발생하는 경우 디버그 방법#

아티팩트는 GitLab Runner 프로세스를 우회하여 빌드 환경에서 GitLab 인스턴스로 직접 업로드됩니다. 예를 들어:

• Docker 실행기의 경우 Docker 컨테이너에서 업로드가 발생합니다.
• Kubernetes 실행기의 경우 빌드 Pod의 빌드 컨테이너에서 업로드가 발생합니다.

빌드 환경에서 GitLab 인스턴스로의 네트워크 경로가 GitLab Runner에서 GitLab 인스턴스로의 경로와 다를 수 있습니다.

아티팩트 업로드를 활성화하려면 업로드 경로의 모든 컴포넌트가 빌드 환경에서 GitLab 인스턴스로의 POST 요청을 허용하는지 확인하세요.

기본적으로 아티팩트 업로더는 업로드 URL과 업로드 응답의 HTTP 상태 코드를 로그에 기록합니다. 이 정보는 어떤 시스템이 오류를 발생시켰거나 아티팩트 업로드를 차단했는지 이해하기에 충분하지 않습니다. 아티팩트 업로드 이슈를 문제 해결하려면 업로드 응답의 헤더와 본문을 보기 위해 업로드 시도에 대한 디버그 로깅을 활성화하세요.

업로드가 GitLab에 도달했지만 오류 상태 코드로 실패하는 경우(예: 비성공적인 응답 상태 코드 생성), GitLab 인스턴스 자체를 조사하세요. 일반적인 아티팩트 업로드 이슈는 GitLab 문서를 참조하세요.

No URL provided, cache will not be download/uploaded#

이 오류는 GitLab Runner 헬퍼가 유효하지 않은 URL을 받거나 원격 캐시에 액세스하기 위한 미리 서명된 URL이 없을 때 발생합니다. 각 캐시 관련 config.toml 항목과 공급자별 키 및 값을 검토하세요. 유효하지 않은 URL은 URL 구문 요구 사항을 따르지 않는 항목으로 구성될 수 있습니다.

또한 헬퍼 image와 helper_image_flavor가 일치하고 최신 상태인지 확인하세요.

자격 증명 구성에 문제가 있으면 진단 오류 메시지가 GitLab Runner 프로세스 로그에 추가됩니다.

오류: warning: You appear to have cloned an empty repository.#

HTTP(s)를 사용하여 git clone을 실행하고(GitLab Runner로 또는 테스트를 위해 수동으로) 다음 출력이 표시될 때:

$ git clone https://git.example.com/user/repo.git

Cloning into 'repo'...
warning: You appear to have cloned an empty repository.

GitLab 서버 설치에서 HTTP 프록시 구성이 올바르게 수행되었는지 확인하세요. 자체 구성이 있는 HTTP 프록시를 사용할 때 요청이 GitLab Unicorn 소켓이 아닌 GitLab Workhorse 소켓으로 프록시되는지 확인하세요.

HTTP(S)를 통한 Git 프로토콜은 GitLab Workhorse에 의해 처리되므로 이것이 GitLab의 기본 진입점입니다.

Linux 패키지 설치를 사용하고 있지만 번들된 NGINX 서버를 사용하고 싶지 않다면 비번들 웹 서버 사용을 참조하세요.

GitLab Recipes 리포지터리에는 Apache와 NGINX에 대한 웹 서버 구성 예시가 있습니다.

소스에서 설치된 GitLab을 사용하는 경우 위의 문서와 예시를 참조하세요. 모든 HTTP(S) 트래픽이 GitLab Workhorse를 통과하는지 확인하세요.

사용자 이슈 예시를 참조하세요.

오류: Timezone 또는 OffPeakTimezone 사용 시 zoneinfo.zip: no such file or directory 오류#

[[docker.machine.autoscaling]] 기간을 설명하는 시간대를 구성할 수 있습니다. 이 기능은 대부분의 Unix 시스템에서 즉시 작동해야 합니다. 그러나 일부 Unix 시스템과 대부분의 비Unix 시스템(GitLab Runner 바이너리를 사용할 수 있는 Windows 등)에서 러너는 다음 오류와 함께 시작 시 충돌할 수 있습니다:

Failed to load config Invalid OffPeakPeriods value: open /usr/local/go/lib/time/zoneinfo.zip: no such file or directory

이 오류는 Go의 time 패키지에 의해 발생합니다. Go는 지정된 시간대의 구성을 로드하기 위해 IANA 시간대 데이터베이스를 사용합니다. 대부분의 Unix 시스템에서 이 데이터베이스는 이미 잘 알려진 경로 중 하나에 있습니다(/usr/share/zoneinfo, /usr/share/lib/zoneinfo, /usr/lib/locale/TZ/). Go의 time 패키지는 이 세 가지 경로 모두에서 시간대 데이터베이스를 찾습니다. 찾지 못하지만 머신에 Go 개발 환경이 구성되어 있으면 $GOROOT/lib/time/zoneinfo.zip 파일로 폴백합니다.

해당 경로 중 어느 것도 없는 경우(예: 프로덕션 Windows 호스트) 위의 오류가 발생합니다.

시스템이 IANA 시간대 데이터베이스를 지원하지만 기본적으로 사용할 수 없는 경우 설치를 시도할 수 있습니다. Linux 시스템의 경우 예를 들어 다음과 같이 할 수 있습니다:

# Debian/Ubuntu 기반 시스템
sudo apt-get install tzdata

# RPM 기반 시스템
sudo yum install tzdata

# Linux Alpine
sudo apk add -U tzdata

시스템이 이 데이터베이스를 네이티브 방식으로 제공하지 않는 경우 다음 단계에 따라 OffPeakTimezone이 작동하도록 할 수 있습니다:

1. zoneinfo.zip을 다운로드합니다. v9.1.0 버전부터 태그된 경로에서 파일을 다운로드할 수 있습니다. 이 경우 zoneinfo.zip 다운로드 URL에서 latest를 태그 이름(예: v9.1.0)으로 교체해야 합니다.

2. 이 파일을 잘 알려진 디렉토리에 저장합니다. config.toml 파일이 있는 동일한 디렉토리를 사용하는 것이 좋습니다. 예를 들어 Windows 머신에서 러너를 호스팅하고 구성 파일이 C:\gitlab-runner\config.toml에 저장된 경우 zoneinfo.zip을 C:\gitlab-runner\zoneinfo.zip에 저장합니다.

3. zoneinfo.zip 파일의 전체 경로를 포함하는 ZONEINFO 환경 변수를 설정합니다. run 명령을 사용하여 러너를 시작하는 경우 다음과 같이 할 수 있습니다:

   ZONEINFO=/etc/gitlab-runner/zoneinfo.zip gitlab-runner run <other options ...>
   

   또는 Windows를 사용하는 경우:

   C:\gitlab-runner> set ZONEINFO=C:\gitlab-runner\zoneinfo.zip
   C:\gitlab-runner> gitlab-runner run <other options ...>
   

   GitLab Runner를 시스템 서비스로 시작하는 경우 서비스 구성을 업데이트하거나 재정의해야 합니다:

   • Unix 시스템에서는 서비스 관리자 소프트웨어를 통해 설정을 수정합니다.
   • Windows에서는 시스템 설정을 통해 GitLab Runner 사용자가 사용할 수 있는 환경 변수 목록에 ZONEINFO 변수를 추가합니다.

GitLab Runner 인스턴스를 두 개 이상 실행할 수 없는 이유는 무엇인가요?#

실행할 수 있지만 동일한 config.toml 파일을 공유하지 않아야 합니다.

동일한 구성 파일을 사용하여 GitLab Runner의 여러 인스턴스를 실행하면 예상치 못한 디버그하기 어려운 동작이 발생할 수 있습니다. 특정 config.toml 파일은 한 번에 GitLab Runner의 단일 인스턴스에서만 사용할 수 있습니다.

작업이 시작되기 전에 지연이 발생함#

일부 프로젝트의 작업이 다른 프로젝트의 작업이 즉시 실행되는 동안 시작되기 전에 상당한 지연이 발생하는 경우 롱 폴링 이슈를 경험하고 있을 수 있습니다.

증상:

• 작업이 대기열에 있지만 실행을 시작하는 데 비정상적으로 오랜 시간이 걸립니다(일반적으로 GitLab 인스턴스 롱 폴링 타임아웃과 일치).
• 일부 러너가 멈춘 것처럼 보이는 반면 다른 러너는 정상적으로 작업을 처리합니다.
• GitLab Runner 로그에 CONFIGURATION: Long polling issues detected가 표시됩니다.

원인:

이 이슈는 GitLab Runner 워커가 GitLab에 대한 롱 폴링 요청에 멈혀 다른 작업이 신속하게 처리되지 못할 때 발생합니다. 이러한 이슈는 구성에 따라 성능 병목에서 완전한 교착 상태까지 다양합니다. 이 이슈는 GitLab Workhorse apiCiLongPollingDuration 설정(기본값: 50s)으로 제어되는 GitLab CI/CD 롱 폴링 기능과 관련이 있습니다.

해결책:

이러한 이슈는 여러 구성 시나리오에서 발생할 수 있습니다. 원인, 구성 예시 및 해결책에 대한 포괄적인 정보는 고급 구성 문서의 롱 폴링 이슈 섹션을 참조하세요.

Job failed (system failure): preparing environment:#

이 오류는 종종 셸이 프로파일을 로드하고 스크립트 중 하나가 실패를 일으키기 때문에 발생합니다.

실패를 일으키는 것으로 알려진 dotfiles 예시:

• .bash_logout
• .condarc
• .rvmrc

SELinux도 이 오류의 원인이 될 수 있습니다. SELinux 감사 로그를 확인하여 이를 확인할 수 있습니다:

sealert -a /var/log/audit/audit.log

Cleaning up 단계 후 러너가 갑자기 종료됨#

CrowdStrike Falcon Sensor가 "컨테이너 드리프트 감지" 설정이 활성화된 경우 작업의 Cleaning up files 단계 후에 Pod를 종료하는 것으로 보고되었습니다. 작업이 완료될 수 있도록 이 설정을 비활성화해야 합니다.

작업이 remote error: tls: bad certificate (exec.go:71:0s)로 실패#

이 오류는 아티팩트를 생성하는 작업 중에 시스템 시간이 크게 변경될 때 발생할 수 있습니다. 시스템 시간 변경으로 인해 SSL 인증서가 만료되어 러너가 아티팩트를 업로드하려고 할 때 오류가 발생합니다.

아티팩트 업로드 중에 SSL 확인이 성공할 수 있도록 작업 끝에 시스템 시간을 유효한 날짜와 시간으로 변경하세요. 아티팩트 파일의 생성 시간도 변경되었으므로 자동으로 아카이브됩니다.

Helm Chart: ERROR .. Unauthorized#

Helm으로 배포된 러너를 제거하거나 업그레이드하기 전에 GitLab에서 일시 중지하고 모든 작업이 완료될 때까지 기다리세요.

작업이 실행 중인 동안 helm uninstall 또는 helm upgrade로 러너 Pod를 제거하면 작업이 완료될 때 다음과 같은 Unauthorized 오류가 발생할 수 있습니다:

ERROR: Error cleaning up pod: Unauthorized
ERROR: Error cleaning up secrets: Unauthorized
ERROR: Job failed (system failure): Unauthorized

러너가 제거되면 역할 바인딩도 제거되기 때문에 이런 일이 발생할 가능성이 높습니다. 러너 Pod는 작업이 완료될 때까지 계속되다가 러너가 삭제를 시도합니다. 역할 바인딩이 없으면 러너 Pod는 더 이상 액세스 권한이 없습니다.

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

Elasticsearch 서비스 시작 오류 max virtual memory areas vm.max_map_count [65530] is too low#

Elasticsearch 서비스 컨테이너 시작 시 다음과 유사한 오류가 발생할 수 있습니다:

• max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

Elasticsearch는 Elasticsearch가 실행되는 인스턴스에서 설정해야 하는 vm.max_map_count 요구 사항이 있습니다. 플랫폼에 따라 이 값을 올바르게 설정하는 방법은 Elasticsearch 문서를 참조하세요.

오류: Preparing the "docker+machine" executor ERROR: Preparation failed: exit status 1#

이 오류는 Docker 머신이 실행기 가상 머신을 성공적으로 만들 수 없을 때 발생할 수 있습니다. 오류에 대한 자세한 정보를 얻으려면 config.toml에 정의한 것과 동일한 MachineOptions로 가상 머신을 수동으로 만듭니다.

예를 들어: docker-machine create --driver=google --google-project=GOOGLE-PROJECT-ID --google-zone=GOOGLE-ZONE ....

오류: No unique index found for name#

이 오류는 러너를 만들거나 업데이트할 때 데이터베이스에 tags 테이블에 대한 고유 인덱스가 없는 경우 발생할 수 있습니다. GitLab UI에서 Response not successful: Received status code 500 오류가 발생할 수 있습니다.

이 이슈는 장기간에 걸쳐 여러 주요 업그레이드를 거친 인스턴스에 영향을 줄 수 있습니다. 이 이슈를 해결하려면 gitlab:db:deduplicate_tags Rake 작업을 사용하여 테이블의 중복 태그를 통합하세요. 자세한 내용은 Rake 작업을 참조하세요.

오류: Not authorized to perform sts:AssumeRoleWithWebIdentity#

러너의 Kubernetes ServiceAccount 리소스에 대한 IAM 역할을 구성했지만 러너 로그에 sts:AssumeRoleWithWebIdentity를 수행할 수 없다고 표시되면 다음과 같은 오류가 발생할 수 있습니다:

{"error":"Not authorized to perform sts:AssumeRoleWithWebIdentity","level":"error","msg":"error while generating S3 pre-signed URL","time":"2025-10-15T18:07:20Z"}

이 이슈는 IAM 역할의 신뢰된 엔티티 구성의 StringLike 또는 StringEquals 조건에 https://를 포함할 때 발생합니다.

이 이슈를 해결하려면 OIDC URL에서 https://를 제거합니다:

"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
  "StringLike": {
    "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::"
  }
}