InfoGrab DocsInfoGrab Docs

GitLab Pages 관리 문제 해결

요약

GitLab Pages를 관리할 때 다음과 같은 문제가 발생할 수 있습니다. 다음 명령을 실행하면 Pages 데몬 로그를 볼 수 있습니다: 로그 파일은 /var/log/gitlab/gitlab-pages/current에서도 찾을 수 있습니다.

GitLab Pages를 관리할 때 다음과 같은 문제가 발생할 수 있습니다.

GitLab Pages 로그 보기#

다음 명령을 실행하면 Pages 데몬 로그를 볼 수 있습니다:

sudo gitlab-ctl tail gitlab-pages

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

자세한 내용은 로그에서 correlation ID 가져오기를 참고합니다.

GitLab Pages 디버그#

다음 시퀀스 다이어그램은 GitLab Pages 요청이 처리되는 과정을 보여 줍니다. GitLab Pages 사이트가 배포되고 오브젝트 스토리지에서 정적 콘텐츠를 제공하는 방식에 대한 자세한 내용은 GitLab Pages 아키텍처 문서를 참고합니다.

Mermaid 다이어그램 (36줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: GitLab Pages Request Flow
    accDescr: Sequence diagram showing how a user request flows through GitLab Pages components to serve static files.
actor User
participant PagesNGINX as Pages NGINX
participant Pages as GitLab Pages
participant GitlabNGINX as GitLab NGINX
participant GitlabAPI as GitLab Rails
participant ObjectStorage as Object Storage

User->>PagesNGINX: Request to Pages
activate PagesNGINX
PagesNGINX->>Pages: Forwarded to Pages
activate Pages

Pages->>GitlabNGINX: Fetch domain info
activate GitlabNGINX
GitlabNGINX->>GitlabAPI: Forwarded to GitLab API
activate GitlabAPI
GitlabAPI->>GitlabNGINX: 200 OK (domain info)
deactivate GitlabAPI
GitlabNGINX->>Pages: 200 OK (domain info)
deactivate GitlabNGINX

Note right of Pages: Domain information cached in Pages

Pages->>ObjectStorage: Fetch static files
activate ObjectStorage
ObjectStorage->>Pages: 200 OK (files)
deactivate ObjectStorage

Pages->>User: 200 OK (static files served)
deactivate Pages
deactivate PagesNGINX</code></pre></details></div>

오류 로그 식별#

앞의 시퀀스 다이어그램에 표시된 순서대로 로그를 확인해야 합니다. 도메인을 기준으로 필터링하면 관련 로그를 식별하는 데 도움이 됩니다.

로그 테일링을 시작하려면 다음을 수행합니다:

  1. GitLab Pages NGINX 로그는 다음을 실행합니다:

    # View GitLab Pages NGINX error logs
    sudo gitlab-ctl tail nginx/gitlab_pages_error.log
    
    # View GitLab Pages NGINX access logs
    sudo gitlab-ctl tail nginx/gitlab_pages_access.log
    
  2. GitLab Pages 로그는 다음을 실행합니다. 로그에서 correlation ID 식별부터 시작합니다.

    sudo gitlab-ctl tail gitlab-pages
    
  3. GitLab NGINX 로그는 다음을 실행합니다:

    # View GitLab NGINX error logs
    sudo gitlab-ctl tail nginx/gitlab_error.log
    
    # View GitLab NGINX access logs
    sudo gitlab-ctl tail nginx/gitlab_access.log
    
  4. GitLab Rails 로그는 다음을 실행합니다. 이 로그는 GitLab Pages 로그의 correlation_id를 기준으로 필터링할 수 있습니다.

    sudo gitlab-ctl tail gitlab-rails
    

인가 코드 흐름#

다음 시퀀스 차트는 보호된 Pages 사이트에 액세스할 때 사용자, GitLab Pages, GitLab Rails 사이에서 이루어지는 OAuth 인증 흐름을 보여 줍니다.

자세한 내용은 GitLab OAuth 인가 코드 흐름을 참고합니다.

Mermaid 다이어그램 (53줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
   accTitle: GitLab Pages OAuth Flow
   accDescr: Sequence diagram showing the OAuth authentication flow between User, GitLab Pages, and GitLab Rails for accessing protected pages sites.

actor User participant PagesService as GitLab Pages participant GitlabApp as GitLab Rails

User->>PagesService: GET Request for site activate PagesService PagesService-->>User: 302 Redirect to project subdomain https://projects.gitlab.io/auth?state=state1 deactivate PagesService Note left of User: Cookie state1

User->>PagesService: GET https://projects.gitlab.io/auth?state=state1 activate PagesService PagesService-->>User: 302 Redirect to gitlab.com/oauth/authorize?state=state1 deactivate PagesService

User->>GitlabApp: GET oauth/authorize?state=state1 activate GitlabApp GitlabApp-->>User: 200 OK (authorization form) deactivate GitlabApp

User->>GitlabApp: POST authorization form activate GitlabApp GitlabApp-->>User: 302 Redirect to oauth/redirect deactivate GitlabApp

User->>GitlabApp: GET oauth/redirect?state=state1 activate GitlabApp GitlabApp-->>User: 200 OK (with auth code) deactivate GitlabApp

User->>PagesService: GET https://projects.gitlab.io/auth?code=code1&amp;state=state1 activate PagesService PagesService->>GitlabApp: POST oauth/token with code=code1 activate GitlabApp GitlabApp-->>PagesService: 200 OK (access token) deactivate GitlabApp PagesService-->>User: 302 Redirect to https://[namespace].gitlab.io/auth?code=code2&state=state1 deactivate PagesService

User->>PagesService: GET https://[namespace].gitlab.io/auth?code=code2&state=state1 activate PagesService PagesService-->>User: 302 Redirect to site deactivate PagesService

User->>PagesService: GET Request for site activate PagesService PagesService-->>User: 200 OK (site content) deactivate PagesService

오류: 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가 기본적으로 IPv6를 사용해 GitLab Pages 서비스에 연결하려 할 수 있습니다. 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를 실행하면, Pages를 제공하려 할 때 다음과 비슷한 오류와 함께 간헐적인 502 오류가 발생할 수 있습니다:

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

GitLab Pages는 bind mount를 /etc/hosts 같은 파일이 포함된 /tmp/gitlab-pages-* 안에 생성합니다. 그러나 systemd가 정기적으로 /tmp/ 디렉터리를 정리할 수 있어 DNS 구성이 사라질 수 있습니다.

systemd가 Pages 관련 콘텐츠를 정리하지 않도록 하려면 다음을 수행합니다:

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

    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 로그에 다음 오류 중 하나가 표시되는 경우입니다:

  • context deadline exceeded 오류:

    "error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source"
    
  • HTTP/HTTPS 프로토콜 불일치 오류:

    "error":"Get \"https://gitlab.example.com/api/v4/internal/pages?host=example.com\": http: server gave HTTP response to HTTPS client","level":"error","msg":"could not fetch domain information from a source"
    

    이 오류는 요청이 GitLab에 도달하기 전에 로드 밸런서나 역방향 프록시가 TLS를 종료할 때 발생합니다. Pages는 HTTPS external_url로 연결하려 하지만 일반 HTTP 응답을 받습니다.

이 문제를 해결하려면 외부 URL을 우회하여 로컬 GitLab Rails 인스턴스와 직접 통신하도록 internal_gitlab_server를 설정합니다:

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

    gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080'
    
  2. GitLab Pages를 재시작합니다:

    sudo gitlab-ctl restart gitlab-pages
    

GitLab Pages 요청이 Pages 콘텐츠 대신 로그인 페이지로 리다이렉트되는 경우#

GitLab Pages가 올바르게 구성된 것처럼 보이지만 요청이 Pages 데몬에 도달하지 않는 경우가 있습니다. 대신 올바른 자격 증명과 권한이 있어도 사용자가 GitLab 로그인 페이지로 계속 리다이렉트됩니다.

이 동작은 메인 GitLab 인스턴스와 GitLab Pages가 같은 NGINX listen 그룹에 속하지 않을 때 발생할 수 있습니다.

nginx['listen_addresses']를 특정 IP 주소로 설정했다면, 그에 맞는 pages_nginx['listen_addresses'] 값이 있어야 합니다.

이 문제를 해결하려면 메인 GitLab 인스턴스와 GitLab Pages가 같은 listen 그룹에 속하도록 두 쪽에 동일한 listen_addresses 값이 구성되어 있는지 확인합니다:

  1. /etc/gitlab/gitlab.rb를 편집하여 메인 GitLab 인스턴스와 GitLab Pages가 일치하는 listen_addresses를 갖도록 합니다. 예를 들면 다음과 같습니다:

    nginx['listen_addresses']       = ['10.74.12.5']
    pages_nginx['listen_addresses'] = ['10.74.12.5']
    
  2. GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
    

두 컴포넌트가 같은 IP 주소에서 수신하면 NGINX가 server_name을 올바르게 평가하여 로그인 페이지로 리다이렉트하는 대신 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 인스턴스를 여러 개 실행하면, 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 인스턴스에서 별도 서버에서 GitLab Pages 실행의 8~10단계를 따릅니다.

AWS Network Load Balancer와 GitLab Pages를 사용할 때 발생하는 간헐적인 502 오류#

클라이언트 IP 보존이 켜진 Network Load Balancer를 사용하고 요청이 소스 서버로 루프백되면 연결 시간이 초과됩니다. 이 문제는 핵심 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로 무작위 문자열을 얻습니다. 이를 위해 호스트 OS에서 getrandom 시스템 호출 또는 /dev/urandom을 사용할 수 있어야 합니다. 공식 지원 운영 체제로 업그레이드하는 것을 권장합니다.

요청된 범위가 유효하지 않거나 형식이 잘못되었거나 알 수 없음#

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

  1. 오른쪽 상단에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Applications > GitLab Pages를 선택합니다.
  3. 애플리케이션을 편집합니다.
  4. Scopes 아래에서 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이 자동으로 앞에 붙이므로 여기서는 생략합니다.

Pages 데몬이 권한 거부 오류로 실패#

/tmp가 noexec로 마운트되어 있으면 Pages 데몬이 다음과 같은 오류와 함께 시작하지 못합니다:

{"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을 선택합니다.
    2. Applications를 선택한 다음 Add new application을 선택합니다.
    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로 파일을 동기화하는 별도 서버에서 Pages를 실행하고 있다면, 공유 Pages 디렉터리가 메인 GitLab 서버와 GitLab Pages 서버에서 서로 다른 경로에 마운트되어 있다는 뜻일 수 있습니다.

이 경우 오브젝트 스토리지를 구성하고 기존 Pages 데이터를 그곳으로 마이그레이션하는 것을 강력히 권장합니다.

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

GitLab Pages deploy job이 is not a recognized provider 오류로 실패#

pages job은 성공했지만 deploy job이 "is not a recognized provider" 오류를 반환하는 경우입니다:

GitLab Pages 파이프라인에서 pages job은 성공했지만 deploy job에서 오류가 표시됩니다.

is not a recognized provider 오류 메시지는 GitLab이 오브젝트 스토리지용 클라우드 공급자에 연결할 때 사용하는 fog gem에서 나올 수 있습니다.

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

  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: job이 포함되어 있는지 확인합니다.
  2. 현재 프로젝트의 파이프라인을 확인하여 pages:deploy job이 실행되고 있는지 확인합니다.

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

namespace_in_path가 켜진 별도의 Pages 서버를 사용하고 있으면 UI가 잘못된 URL을 표시할 때 발생하는 404 오류를 참고합니다.

404 오류: Pages UI가 잘못된 URL을 표시할 때 Page not found#

별도의 GitLab Pages 서버에서 namespace_in_path를 구성하고 켰다면 404 Page not found 오류가 발생할 수 있습니다.

이 오류는 GitLab Pages 서버나 메인 GitLab 서버에서 namespace_in_path 설정이 잘못 구성되었거나 누락된 경우에 발생합니다.

전역 설정 namespace_in_path는 GitLab Pages 사이트의 URL 구조를 결정합니다. GitLab 서버와 GitLab Pages 서버는 이 설정에 동일한 값을 지정해야 합니다.

이 오류를 해결하려면 다음을 수행합니다:

  1. /etc/gitlab/gitlab.rb 파일을 엽니다:

    1. GitLab 서버 구성이 다음과 같은지 확인합니다:

      gitlab_pages['namespace_in_path'] = true
      
    2. GitLab Pages 서버 구성이 동일한지 확인합니다:

         gitlab_pages['namespace_in_path'] = true
      
  2. 파일을 저장합니다.

  3. 변경 사항이 적용되도록 두 서버에서 GitLab을 재구성합니다.

job 아티팩트를 볼 때 발생하는 404 오류#

Pages 사이트가 정상적으로 로드되고 인증도 성공하지만, job 아티팩트 링크가 404 오류를 반환할 수 있습니다.

Pages 데몬은 아티팩트 요청을 artifacts_server_url의 GitLab API로 프록시합니다. 이 요청은 URL 인코딩된 프로젝트 경로를 사용하므로 프로젝트 경로에 인코딩된 슬래시(%2F)가 들어 있습니다. GitLab 앞단의 역방향 프록시가 이 문자를 디코딩하면 URL이 더 이상 API 경로와 일치하지 않습니다. 그러면 API가 404를 반환합니다.

Pages 로그에는 404 응답만 기록되고 API가 받은 URL은 기록되지 않습니다. 원인을 확인하려면 역방향 프록시 로그에서 해당 요청을 확인합니다.

전체 구성 예시는 역방향 프록시를 사용할 때 발생하는 404 Not Found를 참고합니다.

503 오류 Client authentication failed due to unknown client#

Pages가 등록된 OAuth 애플리케이션이고 액세스 제어가 켜져 있다면, 이 오류는 /etc/gitlab/gitlab-secrets.json에 저장된 인증 토큰이 유효하지 않게 되었음을 나타냅니다:

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

해결하려면 다음을 수행합니다:

  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
    

멀티 노드 OAuth 시크릿 동기화#

여러 노드에서 GitLab Pages를 실행할 때 Pages OAuth 시크릿은 모든 노드에서 동일해야 합니다. 시크릿이 동기화되지 않으면 일부 노드가 같은 Client authentication failed due to unknown client 오류로 인증 요청을 거부할 수 있습니다.

이 문제를 해결하려면 다음을 수행합니다:

  1. 모든 GitLab 노드에서 시크릿 파일을 백업합니다:

    sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)
    
  2. 첫 번째 노드의 /etc/gitlab/gitlab-secrets.json 파일에서 다음을 수행합니다:

    1. gitlab_pages 섹션을 제거합니다.

    2. 파일을 저장합니다.

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

      sudo gitlab-ctl reconfigure
      
    4. 업데이트된 gitlab_pages 섹션을 복사합니다.

  3. 다른 모든 노드에서 업데이트된 gitlab_pages 섹션을 해당 gitlab-secrets.json 파일에 붙여 넣고 저장합니다.

  4. gitlab-pages-config 파일이 업데이트된 시크릿으로 채워지도록 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
    
  5. 각 노드에서 /etc/gitlab/gitlab-secrets.json의 gitlab_pages 섹션과 /var/opt/gitlab/gitlab-pages/gitlab-pages-config 파일의 내용을 비교하여 시크릿이 모든 노드에서 일치하는지 확인합니다.

오류: Response size over 104857600 bytes#

pages job은 성공했지만 deploy job이 실패하면서 Response size over 104857600 bytes 오류가 발생할 수 있습니다.

이 오류는 압축을 해제한 Pages 콘텐츠가 최대 Gzip 압축 크기 제한을 초과할 때 발생합니다.

이 문제를 해결하려면 max_http_decompressed_size 제한을 늘립니다. 다음 방법 중 하나를 사용합니다:

GitLab Pages 관리 문제 해결

GitLab v19.5
Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

GitLab Pages를 관리할 때 다음과 같은 문제가 발생할 수 있습니다. 다음 명령을 실행하면 Pages 데몬 로그를 볼 수 있습니다: 로그 파일은 /var/log/gitlab/gitlab-pages/current에서도 찾을 수 있습니다.

GitLab Pages를 관리할 때 다음과 같은 문제가 발생할 수 있습니다.

GitLab Pages 로그 보기#

다음 명령을 실행하면 Pages 데몬 로그를 볼 수 있습니다:

sudo gitlab-ctl tail gitlab-pages

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

자세한 내용은 로그에서 correlation ID 가져오기를 참고합니다.

GitLab Pages 디버그#

다음 시퀀스 다이어그램은 GitLab Pages 요청이 처리되는 과정을 보여 줍니다. GitLab Pages 사이트가 배포되고 오브젝트 스토리지에서 정적 콘텐츠를 제공하는 방식에 대한 자세한 내용은 GitLab Pages 아키텍처 문서를 참고합니다.

Mermaid 다이어그램 (36줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: GitLab Pages Request Flow
    accDescr: Sequence diagram showing how a user request flows through GitLab Pages components to serve static files.
actor User
participant PagesNGINX as Pages NGINX
participant Pages as GitLab Pages
participant GitlabNGINX as GitLab NGINX
participant GitlabAPI as GitLab Rails
participant ObjectStorage as Object Storage

User-&gt;&gt;PagesNGINX: Request to Pages
activate PagesNGINX
PagesNGINX-&gt;&gt;Pages: Forwarded to Pages
activate Pages

Pages-&gt;&gt;GitlabNGINX: Fetch domain info
activate GitlabNGINX
GitlabNGINX-&gt;&gt;GitlabAPI: Forwarded to GitLab API
activate GitlabAPI
GitlabAPI-&gt;&gt;GitlabNGINX: 200 OK (domain info)
deactivate GitlabAPI
GitlabNGINX-&gt;&gt;Pages: 200 OK (domain info)
deactivate GitlabNGINX

Note right of Pages: Domain information cached in Pages

Pages-&gt;&gt;ObjectStorage: Fetch static files
activate ObjectStorage
ObjectStorage-&gt;&gt;Pages: 200 OK (files)
deactivate ObjectStorage

Pages-&gt;&gt;User: 200 OK (static files served)
deactivate Pages
deactivate PagesNGINX</code></pre></details></div>

오류 로그 식별#

앞의 시퀀스 다이어그램에 표시된 순서대로 로그를 확인해야 합니다. 도메인을 기준으로 필터링하면 관련 로그를 식별하는 데 도움이 됩니다.

로그 테일링을 시작하려면 다음을 수행합니다:

  1. GitLab Pages NGINX 로그는 다음을 실행합니다:

    # View GitLab Pages NGINX error logs
    sudo gitlab-ctl tail nginx/gitlab_pages_error.log
    
    # View GitLab Pages NGINX access logs
    sudo gitlab-ctl tail nginx/gitlab_pages_access.log
    
  2. GitLab Pages 로그는 다음을 실행합니다. 로그에서 correlation ID 식별부터 시작합니다.

    sudo gitlab-ctl tail gitlab-pages
    
  3. GitLab NGINX 로그는 다음을 실행합니다:

    # View GitLab NGINX error logs
    sudo gitlab-ctl tail nginx/gitlab_error.log
    
    # View GitLab NGINX access logs
    sudo gitlab-ctl tail nginx/gitlab_access.log
    
  4. GitLab Rails 로그는 다음을 실행합니다. 이 로그는 GitLab Pages 로그의 correlation_id를 기준으로 필터링할 수 있습니다.

    sudo gitlab-ctl tail gitlab-rails
    

인가 코드 흐름#

다음 시퀀스 차트는 보호된 Pages 사이트에 액세스할 때 사용자, GitLab Pages, GitLab Rails 사이에서 이루어지는 OAuth 인증 흐름을 보여 줍니다.

자세한 내용은 GitLab OAuth 인가 코드 흐름을 참고합니다.

Mermaid 다이어그램 (53줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
   accTitle: GitLab Pages OAuth Flow
   accDescr: Sequence diagram showing the OAuth authentication flow between User, GitLab Pages, and GitLab Rails for accessing protected pages sites.

actor User participant PagesService as GitLab Pages participant GitlabApp as GitLab Rails

User->>PagesService: GET Request for site activate PagesService PagesService-->>User: 302 Redirect to project subdomain https://projects.gitlab.io/auth?state=state1 deactivate PagesService Note left of User: Cookie state1

User->>PagesService: GET https://projects.gitlab.io/auth?state=state1 activate PagesService PagesService-->>User: 302 Redirect to gitlab.com/oauth/authorize?state=state1 deactivate PagesService

User->>GitlabApp: GET oauth/authorize?state=state1 activate GitlabApp GitlabApp-->>User: 200 OK (authorization form) deactivate GitlabApp

User->>GitlabApp: POST authorization form activate GitlabApp GitlabApp-->>User: 302 Redirect to oauth/redirect deactivate GitlabApp

User->>GitlabApp: GET oauth/redirect?state=state1 activate GitlabApp GitlabApp-->>User: 200 OK (with auth code) deactivate GitlabApp

User->>PagesService: GET https://projects.gitlab.io/auth?code=code1&amp;state=state1 activate PagesService PagesService->>GitlabApp: POST oauth/token with code=code1 activate GitlabApp GitlabApp-->>PagesService: 200 OK (access token) deactivate GitlabApp PagesService-->>User: 302 Redirect to https://[namespace].gitlab.io/auth?code=code2&state=state1 deactivate PagesService

User->>PagesService: GET https://[namespace].gitlab.io/auth?code=code2&state=state1 activate PagesService PagesService-->>User: 302 Redirect to site deactivate PagesService

User->>PagesService: GET Request for site activate PagesService PagesService-->>User: 200 OK (site content) deactivate PagesService

오류: 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가 기본적으로 IPv6를 사용해 GitLab Pages 서비스에 연결하려 할 수 있습니다. 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를 실행하면, Pages를 제공하려 할 때 다음과 비슷한 오류와 함께 간헐적인 502 오류가 발생할 수 있습니다:

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

GitLab Pages는 bind mount를 /etc/hosts 같은 파일이 포함된 /tmp/gitlab-pages-* 안에 생성합니다. 그러나 systemd가 정기적으로 /tmp/ 디렉터리를 정리할 수 있어 DNS 구성이 사라질 수 있습니다.

systemd가 Pages 관련 콘텐츠를 정리하지 않도록 하려면 다음을 수행합니다:

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

    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 로그에 다음 오류 중 하나가 표시되는 경우입니다:

  • context deadline exceeded 오류:

    "error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source"
    
  • HTTP/HTTPS 프로토콜 불일치 오류:

    "error":"Get \"https://gitlab.example.com/api/v4/internal/pages?host=example.com\": http: server gave HTTP response to HTTPS client","level":"error","msg":"could not fetch domain information from a source"
    

    이 오류는 요청이 GitLab에 도달하기 전에 로드 밸런서나 역방향 프록시가 TLS를 종료할 때 발생합니다. Pages는 HTTPS external_url로 연결하려 하지만 일반 HTTP 응답을 받습니다.

이 문제를 해결하려면 외부 URL을 우회하여 로컬 GitLab Rails 인스턴스와 직접 통신하도록 internal_gitlab_server를 설정합니다:

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

    gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080'
    
  2. GitLab Pages를 재시작합니다:

    sudo gitlab-ctl restart gitlab-pages
    

GitLab Pages 요청이 Pages 콘텐츠 대신 로그인 페이지로 리다이렉트되는 경우#

GitLab Pages가 올바르게 구성된 것처럼 보이지만 요청이 Pages 데몬에 도달하지 않는 경우가 있습니다. 대신 올바른 자격 증명과 권한이 있어도 사용자가 GitLab 로그인 페이지로 계속 리다이렉트됩니다.

이 동작은 메인 GitLab 인스턴스와 GitLab Pages가 같은 NGINX listen 그룹에 속하지 않을 때 발생할 수 있습니다.

nginx['listen_addresses']를 특정 IP 주소로 설정했다면, 그에 맞는 pages_nginx['listen_addresses'] 값이 있어야 합니다.

이 문제를 해결하려면 메인 GitLab 인스턴스와 GitLab Pages가 같은 listen 그룹에 속하도록 두 쪽에 동일한 listen_addresses 값이 구성되어 있는지 확인합니다:

  1. /etc/gitlab/gitlab.rb를 편집하여 메인 GitLab 인스턴스와 GitLab Pages가 일치하는 listen_addresses를 갖도록 합니다. 예를 들면 다음과 같습니다:

    nginx['listen_addresses']       = ['10.74.12.5']
    pages_nginx['listen_addresses'] = ['10.74.12.5']
    
  2. GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
    

두 컴포넌트가 같은 IP 주소에서 수신하면 NGINX가 server_name을 올바르게 평가하여 로그인 페이지로 리다이렉트하는 대신 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 인스턴스를 여러 개 실행하면, 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 인스턴스에서 별도 서버에서 GitLab Pages 실행의 8~10단계를 따릅니다.

AWS Network Load Balancer와 GitLab Pages를 사용할 때 발생하는 간헐적인 502 오류#

클라이언트 IP 보존이 켜진 Network Load Balancer를 사용하고 요청이 소스 서버로 루프백되면 연결 시간이 초과됩니다. 이 문제는 핵심 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로 무작위 문자열을 얻습니다. 이를 위해 호스트 OS에서 getrandom 시스템 호출 또는 /dev/urandom을 사용할 수 있어야 합니다. 공식 지원 운영 체제로 업그레이드하는 것을 권장합니다.

요청된 범위가 유효하지 않거나 형식이 잘못되었거나 알 수 없음#

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

  1. 오른쪽 상단에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Applications > GitLab Pages를 선택합니다.
  3. 애플리케이션을 편집합니다.
  4. Scopes 아래에서 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이 자동으로 앞에 붙이므로 여기서는 생략합니다.

Pages 데몬이 권한 거부 오류로 실패#

/tmp가 noexec로 마운트되어 있으면 Pages 데몬이 다음과 같은 오류와 함께 시작하지 못합니다:

{"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을 선택합니다.
    2. Applications를 선택한 다음 Add new application을 선택합니다.
    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로 파일을 동기화하는 별도 서버에서 Pages를 실행하고 있다면, 공유 Pages 디렉터리가 메인 GitLab 서버와 GitLab Pages 서버에서 서로 다른 경로에 마운트되어 있다는 뜻일 수 있습니다.

이 경우 오브젝트 스토리지를 구성하고 기존 Pages 데이터를 그곳으로 마이그레이션하는 것을 강력히 권장합니다.

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

GitLab Pages deploy job이 is not a recognized provider 오류로 실패#

pages job은 성공했지만 deploy job이 "is not a recognized provider" 오류를 반환하는 경우입니다:

GitLab Pages 파이프라인에서 pages job은 성공했지만 deploy job에서 오류가 표시됩니다.

is not a recognized provider 오류 메시지는 GitLab이 오브젝트 스토리지용 클라우드 공급자에 연결할 때 사용하는 fog gem에서 나올 수 있습니다.

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

  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: job이 포함되어 있는지 확인합니다.
  2. 현재 프로젝트의 파이프라인을 확인하여 pages:deploy job이 실행되고 있는지 확인합니다.

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

namespace_in_path가 켜진 별도의 Pages 서버를 사용하고 있으면 UI가 잘못된 URL을 표시할 때 발생하는 404 오류를 참고합니다.

404 오류: Pages UI가 잘못된 URL을 표시할 때 Page not found#

별도의 GitLab Pages 서버에서 namespace_in_path를 구성하고 켰다면 404 Page not found 오류가 발생할 수 있습니다.

이 오류는 GitLab Pages 서버나 메인 GitLab 서버에서 namespace_in_path 설정이 잘못 구성되었거나 누락된 경우에 발생합니다.

전역 설정 namespace_in_path는 GitLab Pages 사이트의 URL 구조를 결정합니다. GitLab 서버와 GitLab Pages 서버는 이 설정에 동일한 값을 지정해야 합니다.

이 오류를 해결하려면 다음을 수행합니다:

  1. /etc/gitlab/gitlab.rb 파일을 엽니다:

    1. GitLab 서버 구성이 다음과 같은지 확인합니다:

      gitlab_pages['namespace_in_path'] = true
      
    2. GitLab Pages 서버 구성이 동일한지 확인합니다:

         gitlab_pages['namespace_in_path'] = true
      
  2. 파일을 저장합니다.

  3. 변경 사항이 적용되도록 두 서버에서 GitLab을 재구성합니다.

job 아티팩트를 볼 때 발생하는 404 오류#

Pages 사이트가 정상적으로 로드되고 인증도 성공하지만, job 아티팩트 링크가 404 오류를 반환할 수 있습니다.

Pages 데몬은 아티팩트 요청을 artifacts_server_url의 GitLab API로 프록시합니다. 이 요청은 URL 인코딩된 프로젝트 경로를 사용하므로 프로젝트 경로에 인코딩된 슬래시(%2F)가 들어 있습니다. GitLab 앞단의 역방향 프록시가 이 문자를 디코딩하면 URL이 더 이상 API 경로와 일치하지 않습니다. 그러면 API가 404를 반환합니다.

Pages 로그에는 404 응답만 기록되고 API가 받은 URL은 기록되지 않습니다. 원인을 확인하려면 역방향 프록시 로그에서 해당 요청을 확인합니다.

전체 구성 예시는 역방향 프록시를 사용할 때 발생하는 404 Not Found를 참고합니다.

503 오류 Client authentication failed due to unknown client#

Pages가 등록된 OAuth 애플리케이션이고 액세스 제어가 켜져 있다면, 이 오류는 /etc/gitlab/gitlab-secrets.json에 저장된 인증 토큰이 유효하지 않게 되었음을 나타냅니다:

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

해결하려면 다음을 수행합니다:

  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
    

멀티 노드 OAuth 시크릿 동기화#

여러 노드에서 GitLab Pages를 실행할 때 Pages OAuth 시크릿은 모든 노드에서 동일해야 합니다. 시크릿이 동기화되지 않으면 일부 노드가 같은 Client authentication failed due to unknown client 오류로 인증 요청을 거부할 수 있습니다.

이 문제를 해결하려면 다음을 수행합니다:

  1. 모든 GitLab 노드에서 시크릿 파일을 백업합니다:

    sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)
    
  2. 첫 번째 노드의 /etc/gitlab/gitlab-secrets.json 파일에서 다음을 수행합니다:

    1. gitlab_pages 섹션을 제거합니다.

    2. 파일을 저장합니다.

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

      sudo gitlab-ctl reconfigure
      
    4. 업데이트된 gitlab_pages 섹션을 복사합니다.

  3. 다른 모든 노드에서 업데이트된 gitlab_pages 섹션을 해당 gitlab-secrets.json 파일에 붙여 넣고 저장합니다.

  4. gitlab-pages-config 파일이 업데이트된 시크릿으로 채워지도록 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
    
  5. 각 노드에서 /etc/gitlab/gitlab-secrets.json의 gitlab_pages 섹션과 /var/opt/gitlab/gitlab-pages/gitlab-pages-config 파일의 내용을 비교하여 시크릿이 모든 노드에서 일치하는지 확인합니다.

오류: Response size over 104857600 bytes#

pages job은 성공했지만 deploy job이 실패하면서 Response size over 104857600 bytes 오류가 발생할 수 있습니다.

이 오류는 압축을 해제한 Pages 콘텐츠가 최대 Gzip 압축 크기 제한을 초과할 때 발생합니다.

이 문제를 해결하려면 max_http_decompressed_size 제한을 늘립니다. 다음 방법 중 하나를 사용합니다: