%%{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>

오류 로그 식별#
이전 시퀀스 다이어그램에 표시된 순서로 로그를 확인해야 합니다. 도메인을 기준으로 필터링하면 관련 로그를 식별하는 데 도움이 됩니다.
로그 테일링을 시작하려면:


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



GitLab Pages 로그의 경우 다음을 실행합니다: 로그에서 correlation ID 식별부터 시작하세요.
sudo gitlab-ctl tail gitlab-pages



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



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) 프로토콜 스킴을 설정하지 않았음을 의미합니다. 수정하려면:


/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



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는 /etc/hosts와 같은 파일을 포함하는 /tmp/gitlab-pages-* 내부에 bind mount를 생성합니다. 그러나 systemd는 정기적으로 /tmp/ 디렉터리를 정리할 수 있으므로 DNS 구성이 손실될 수 있습니다.
Pages 관련 콘텐츠를 systemd가 정리하지 않도록 하려면:


Pages /tmp 디렉터리를 제거하지 않도록 tmpfiles.d에 알립니다:
echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf



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를 설정합니다:


/etc/gitlab/gitlab.rb에 다음을 추가합니다:
gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080'



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 인스턴스를 실행하면 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 네트워크 로드 밸런서와 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이 호스트 OS에서 사용 가능해야 합니다. 공식 지원 운영 체제로 업그레이드하는 것이 권장됩니다.
요청된 범위가 유효하지 않거나 잘못 형성되었거나 알 수 없음#
이 문제는 GitLab Pages OAuth 애플리케이션의 권한에서 비롯됩니다. 수정하려면:

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Applications > GitLab Pages를 선택합니다.
애플리케이션을 편집합니다.
Scopes 아래에서 api 범위가 선택되어 있는지 확인합니다.
변경 사항을 저장합니다.

별도의 Pages 서버를 실행하는 경우 이 설정은 기본 GitLab 서버에서 구성해야 합니다.
와일드카드 DNS 항목을 설정할 수 없는 경우 해결 방법#
와일드카드 DNS 사전 조건을 충족할 수 없는 경우에도 제한된 방식으로 GitLab Pages를 사용할 수 있습니다:

Pages를 사용해야 하는 모든 프로젝트를 단일 그룹 네임스페이스, 예를 들어 pages로 이동합니다.
*.-와일드카드 없이 DNS 항목을 구성합니다. 예를 들어 pages.example.io.
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이 어느 시점에 업데이트된 경우 이 오류가 표시될 수 있습니다. 다음을 확인합니다:


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

오른쪽 상단에서 Admin을 선택합니다.
Applications를 선택한 다음 Add new application을 선택합니다.
Callback URL/Redirect URI가 pages_external_url이 사용하도록 구성된 프로토콜(HTTP 또는 HTTPS)을 사용하는지 확인합니다.



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가 디스크 액세스를 비활성화하도록 구성된 것을 의미합니다.
디스크 액세스를 활성화하려면:


/etc/gitlab/gitlab.rb에서 GitLab Pages의 디스크 액세스를 활성화합니다:
gitlab_pages['enable_disk'] = true



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 배포 작업이 is not a recognized provider 오류로 실패#
pages 작업은 성공하지만 deploy 작업이 "is not a recognized provider" 오류를 주는 경우:

오류 메시지 is not a recognized provider는 GitLab이 오브젝트 스토리지를 위한 클라우드 공급자에 연결하는 데 사용하는 fog gem에서 올 수 있습니다.
수정하려면:


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

Pages 배포를 위한 오브젝트 스토리지를 구성합니다. S3 호환 연결 설정 가이드를 따르세요.
해당 줄을 주석 처리하여 배포를 로컬에 저장합니다.



gitlab.rb 파일에 변경 사항을 저장한 다음 GitLab을 재구성합니다.


404 오류 The page you're looking for could not be found#
GitLab Pages에서 404 Page Not Found 응답을 받는 경우:

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

pages:deploy 작업 없이는 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 서버 모두 이 설정에 대해 동일한 값을 가져야 합니다.
이 오류를 해결하려면:


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


GitLab 서버 구성이 다음인지 확인합니다:
gitlab_pages['namespace_in_path'] = true



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





파일을 저장합니다.


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


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.

해결하려면:


시크릿 파일을 백업합니다:
sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)



/etc/gitlab/gitlab-secrets.json을 편집하고 gitlab_pages 섹션을 제거합니다.


GitLab을 재구성하고 OAuth 토큰을 재생성합니다:
sudo gitlab-ctl reconfigure



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


모든 GitLab 노드에서 시크릿 파일을 백업합니다:
sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.$(date +\%Y\%m\%d)



첫 번째 노드에서 /etc/gitlab/gitlab-secrets.json 파일 내:


gitlab_pages 섹션을 제거합니다.


파일을 저장합니다.


GitLab을 재구성하여 OAuth 토큰을 재생성합니다:
sudo gitlab-ctl reconfigure



업데이트된 gitlab_pages 섹션을 복사합니다.




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


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



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


오류: Response size over 104857600 bytes#
pages 작업은 성공하지만 deploy 작업이 실패하면서 Response size over 104857600 bytes라는 오류가 발생할 수 있습니다.
이 오류는 압축 해제된 Pages 콘텐츠가 최대 Gzip 압축 크기 제한을 초과할 때 발생합니다.
이 문제를 해결하려면 max_http_decompressed_size 제한을 늘리세요. 다음 방법 중 하나를 사용합니다:


Rails 콘솔 세션에서 다음을 실행합니다:
ApplicationSetting.update(max_http_decompressed_size: 1000)



애플리케이션 설정 API를 사용합니다.


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 값으로 구성되어 있는지 확인합니다:


/etc/gitlab/gitlab.rb를 편집하여 메인 GitLab 인스턴스와 GitLab Pages 모두 일치하는 listen_addresses를 갖도록 합니다. 예를 들어:
nginx['listen_addresses']       = ['10.74.12.5']
pages_nginx['listen_addresses'] = ['10.74.12.5']



GitLab을 재구성합니다:
sudo gitlab-ctl reconfigure



두 컴포넌트가 동일한 IP 주소에서 수신 대기하면, NGINX가 server_name을 올바르게 평가하고 로그인 페이지로 리다이렉트하는 대신 GitLab Pages로 요청을 라우팅할 수 있습니다.