GitLab Pages 관리 문제 해결

Tier: Free, Premium, Ultimate Offering: Self-Managed

이 페이지에는 GitLab Pages를 관리하는 동안 만날 수 있는 문제들의 디렉터리이 포함되어 있습니다.

GitLab Pages 로그 보는 방법

다음을 실행하여 Pages 데몬 로그를 볼 수 있습니다. 

sudo gitlab-ctl tail gitlab-pages

또한 로그 파일을 /var/log/gitlab/gitlab-pages/current에서 찾을 수 있습니다.

unsupported protocol scheme \"\""

다음과 같은 오류가 표시된다면: 

{"error":"failed to connect to internal Pages API: Get \"/api/v4/internal/pages/status\": unsupported protocol scheme \"\"","level":"warning","msg":"attempted to connect to the API","time":"2021-06-23T20:03:30Z"}

Pages 서버 설정에서 HTTP(S) 프로토콜 스키마를 설정하지 않았다는 것을 의미합니다. 이를 해결하려면:

  1. /etc/gitlab/gitlab.rb을 편집합니다: 

    gitlab_pages['gitlab_server'] = "https://<your_gitlab_server_public_host_and_port>"
gitlab_pages['internal_gitlab_server'] = "https://<your_gitlab_server_private_host_and_port>" # optional, gitlab_pages['gitlab_server'] is used as default

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

서버가 IPv6에서 듣지 않을 때 GitLab Pages 프록시에 대한 502 오류

일부 경우에, 서버가 IPv6에서 듣지 않더라도 NGINX는 GitLab Pages 서비스에 연결하기 위해 기본적으로 IPv6를 사용할 수 있습니다. 이것이 발생하는지 여부는 gitlab_pages_error.log에 아래와 유사한 항목을 볼 때 식별할 수 있습니다: 

2020/02/24 16:32:05 [error] 112654#0: *4982804 connect() failed (111: Connection refused) while connecting to upstream, client: 123.123.123.123, server: ~^(?<group>.*)\.pages\.example\.com$, request: "GET /-/group/project/-/jobs/1234/artifacts/artifact.txt HTTP/1.1", upstream: "http://[::1]:8090//-/group/project/-/jobs/1234/artifacts/artifact.txt", host: "group.example.com"

이를 해결하기 위해 GitLab Pages listen_proxy 설정에 명시적인 IP와 포트를 설정하여 GitLab Pages 데몬이 청취해야 하는 명시적 주소를 정의합니다: 

gitlab_pages['listen_proxy'] = '127.0.0.1:8090'

간헐적인 502 오류 또는 며칠 후 발생하는 502 오류

systemd 및 tmpfiles.d를 사용하는 시스템에서 Pages를 실행하는 경우, 아래와 유사한 오류가 발생하면서 페이지를 제공할 때 간헐적인 502 오류가 발생할 수 있습니다: 

dial tcp: lookup gitlab.example.com on [::1]:53: dial udp [::1]:53: connect: no route to host"

GitLab Pages는 /tmp/gitlab-pages-* 내부에 /etc/hosts와 같은 파일을 포함하는 bind mount를 생성합니다. 그러나 systemd는 정기적으로 /tmp/ 디렉터리를 정리할 수 있으므로 DNS 구성이 손실될 수 있습니다.

systemd가 Pages와 관련된 내용을 지우지 않도록 하려면:

  1. tmpfiles.d에 Pages /tmp 디렉터리를 제거하지 않도록 지시합니다: 

    echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf

  2. GitLab Pages를 다시 시작합니다: 

    sudo gitlab-ctl restart gitlab-pages

GitLab Pages에 액세스할 수 없음

GitLab Pages에 액세스할 수 없거나 (502 Bad Gateway 오류를 받거나 로그인 루프가 발생할 경우 등) Pages 로그에 다음 오류가 표시되면: 

"error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source"

  1. /etc/gitlab/gitlab.rb에 다음을 추가합니다: 

    gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080'

  2. GitLab Pages를 다시 시작합니다: 

    sudo gitlab-ctl restart gitlab-pages

내부 GitLab API에 연결할 수 없음

다음과 같은 오류가 표시된다면: 

ERRO[0010] Failed to connect to the internal GitLab API after 0.50s  error="failed to connect to internal Pages API: HTTP status: 401"

별도의 서버에서 GitLab Pages를 실행 중이라면 GitLab 서버에서 Pages 서버로 /etc/gitlab/gitlab-secrets.json 파일을 복사해야 합니다.

네트워크 연결 문제나 방화벽 구성 또는 포트가 닫혔을 수 있는 GitLab 서버와 Pages 서버간의 연결 시간 초과와 같은 다른 이유로 인해 발생할 수 있습니다. 예를 들어 연결 시간 초과가 발생하면: 

error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"

Pages가 GitLab API 인스턴스와 통신할 수 없음

domain_config_source=auto의 기본값을 사용하고 여러 인스턴스의 GitLab Pages를 실행하는 경우, 페이지 콘텐츠를 제공하는 중간적인 502 오류 응답이 발생할 수 있습니다. 또한 Pages 로그에서 다음 경고 메시지를 볼 수 있습니다: 

WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized"

이는 GitLab Rails와 GitLab Pages 간의 gitlab-secrets.json 파일이 오래되었을 때 발생할 수 있습니다. 별도의 서버에서 GitLab Pages를 실행하는 방법의 단계 8-10을 따릅니다.

AWS 네트워크 로드 밸런서 및 GitLab Pages를 사용할 때 간헐적인 502 오류

클라이언트 IP 보존이 활성화된 상태에서 네트워크 로드 밸런서를 사용하면 연결이 루프되어 소스 서버로 다시 전송될 때 연결이 타임아웃될 수 있습니다(요청이 소스 서버로 다시 루프되는 경우). 여러 서버에서 코어 GitLab 애플리케이션과 GitLab Pages를 모두 실행하는 GitLab 인스턴스의 경우 또는 단일 컨테이너가 코어 GitLab 애플리케이션과 GitLab Pages를 모두 실행하는 경우에 발생할 수 있습니다.

이 문제를 해결하려면 AWS는 이 문제를 해결하기 위해 IP 타겟 유형을 사용할 것을 권장합니다.

코어 GitLab 애플리케이션과 GitLab Pages를 같은 호스트 또는 컨테이너에서 실행하는 경우 클라이언트 IP 보존을 해제하면 이 문제를 해결할 수 있습니다.

securecookie: failed to generate random iv 및 Failed to save the session으로 인한 500 오류

이 문제는 구 버전의 운영 체제로 인해 발생할 가능성이 가장 높습니다. Pages 데몬은 securecookie 라이브러리를 사용하여 Go의 crypto/rand를 통해 랜덤 문자열을 얻습니다. 이는 호스트 운영 체제에서 getrandom 시스템 호출 또는 /dev/urandom이 사용 가능해야 합니다. 공식적으로 지원되는 운영 체제로 업그레이드하는 것이 권장됩니다.

요청된 범위는 유효하지 않거나 잘못되었거나 알 수 없습니다

이 문제는 GitLab Pages OAuth 애플리케이션의 권한에서 비롯됩니다. 해결 방법은 다음과 같습니다:

  1. 왼쪽 사이드바에서 가장 아래쪽에서 관리 영역(Admin Area)을 선택합니다.
  2. 응용 프로그램 > GitLab Pages를 선택합니다.
  3. 애플리케이션을 편집합니다.
  4. 범위에서 api 범위가 선택되었는지 확인합니다.
  5. 변경 사항을 저장합니다.

별도로 Pages 서버를 실행하는 경우, 이 설정은 주 GitLab 서버에서 구성해야 합니다.

와일드카드 DNS 항목을 설정할 수 없는 경우의 해결 방법

와일드카드 DNS 전제 조건을 충족할 수 없는 경우 GitLab Pages를 제한된 방식으로 사용할 수 있습니다:

  1. Pages를 사용해야 하는 모든 프로젝트를 단일 그룹 네임스페이스(예: pages)로 이동합니다.
  2. *. 와일드카드 없이 DNS 항목을 구성합니다. 예를 들어 pages.example.io와 같이 구성합니다.
  3. gitlab.rb 파일에서 pages_external_url http://example.io/를 구성합니다. 여기서 그룹 네임스페이스를 생략합니다. GitLab에서 자동으로 접두어를 추가하기 때문입니다.

페이지 데몬이 권한 거부 오류로 실패하는 경우

/tmp가 noexec로 마운트된 경우 페이지 데몬은 다음과 같은 오류로 시작하지 못할 수 있습니다. 

{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"}

이 경우 TMPDIR를 noexec로 마운트되지 않은 위치로 변경해야 합니다. 다음을 /etc/gitlab/gitlab.rb에 추가합니다: 

gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'}

추가한 후 sudo gitlab-ctl reconfigure로 재구성하고 sudo gitlab-ctl restart로 GitLab을 다시 시작합니다.

Pages 액세스 제어 사용 시 The redirect URI included is not valid.

pages_external_url이 어느 시점에서 업데이트된 경우 이 오류가 표시될 수 있습니다. 다음을 확인합니다:

  1. 시스템 OAuth 애플리케이션을 확인합니다:

    1. 왼쪽 사이드바에서 가장 아래쪽에서 관리 영역(Admin Area)을 선택합니다.
    2. 응용 프로그램을 선택한 다음 새 응용 프로그램 추가를 선택합니다.
    3. Callback URL/Redirect URI이 pages_external_url이 구성된 프로토콜(HTTP 또는 HTTPS)을 사용하는지 확인합니다.

  2. Redirect URI의 도메인 및 경로 컴포넌트가 유효한지 확인합니다. projects.<pages_external_url>/auth와 같이 보이어야 합니다.

500 오류 cannot serve from disk

Pages에서 500 응답을 받고 다음과 유사한 오류를 만난 경우: 

ERRO[0145] cannot serve from disk                        error="gitlab: disk access is disabled via enable-disk=false" project_id=27 source_path="file:///shared/pages/@hashed/67/06/670671cd97404156226e507973f2ab8330d3022ca96e0c93bdbdb320c41adcaf/pages_deployments/14/artifacts.zip" source_type=zip

이는 GitLab Rails가 GitLab Pages에게 디스크의 위치에서 콘텐츠를 제공하도록 지시하지만, GitLab Pages가 디스크 액세스를 비활성화하도록 구성된 경우를 의미합니다.

디스크 액세스를 활성화하려면 다음을 수행합니다:

  1. /etc/gitlab/gitlab.rb에서 GitLab Pages의 디스크 액세스를 활성화합니다: 

    gitlab_pages['enable_disk'] = true

  2. GitLab을 다시 구성합니다.

httprange: new resource 403 오류

다음과 유사한 오류가 표시되는 경우: 

{"error":"httprange: new resource 403: \"403 Forbidden\"","host":"root.pages.example.com","level":"error","msg":"vfs.Root","path":"/pages1/","time":"2021-06-10T08:45:19Z"}

그리고 별도의 서버에서 페이지를 실행하고 NFS를 통해 파일을 동기화하는 경우, 공유 페이지 디렉터리가 주 GitLab 서버와 GitLab Pages 서버의 다른 경로에 마운트된 것을 의미할 수 있습니다.

이 경우 객체 리포지터리를 구성하고 기존 페이지 데이터를 마이그레이션하는 것이 매우 권장됩니다.

또는 GitLab Pages 공유 디렉터리를 두 서버의 동일한 경로에 마운트할 수 있습니다.

GitLab Pages 배포 작업이 “is not a recognized provider” 오류로 실패하는 경우

pages 작업은 성공하지만 deploy 작업에서 “is not a recognized provider” 오류가 발생하는 경우:

Pages Deploy Failure

오류 메시지 is not a recognized provider는 GitLab이 객체 리포지터리에 연결하기 위해 사용하는 fog 젬에서 올 수 있습니다.

해결 방법은 다음과 같습니다:

  1. gitlab.rb 파일을 확인합니다. gitlab_rails['pages_object_store_enabled']가 활성화되어 있지만 버킷 세부 정보가 구성되지 않은 경우 다음 중 하나를 수행합니다:

    • S3 호환 연결 설정 가이드에 따라 Pages 배포를 위한 객체 리포지터리를 구성합니다.
    • 해당 줄을 주석 처리하여 배포를 로컬로 저장합니다.

  2. gitlab.rb 파일에 적용한 변경 사항을 저장한 후 GitLab을 다시 구성합니다.

404 오류 The page you're looking for could not be found

GitLab Pages에서 404 Page Not Found 응답을 받은 경우:

  1. .gitlab-ci.yml 파일에 작업 pages:가 있는지 확인합니다.
  2. 현재 프로젝트의 파이프라인을 확인하여 작업 pages:deploy가 실행되는지 확인합니다.

pages:deploy 작업이 없으면 GitLab Pages 사이트의 업데이트가 게시되지 않습니다.

503 오류 Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method.

Pages가 등록된 OAuth 애플리케이션이고 액세스 제어가 활성화된 경우, 이 오류는 /etc/gitlab/gitlab-secrets.json에 저장된 인증 토큰이 무효화된 것을 나타냅니다. 해결 방법은 다음과 같습니다:

  1. 시크릿 파일을 백업합니다: 

    sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)
  2. /etc/gitlab/gitlab-secrets.json을 편집하고 gitlab_pages 섹션을 제거합니다.

  3. GitLab을 재구성하고 OAuth 토큰을 재생성합니다: 

    sudo gitlab-ctl reconfigure