GitLab Pages는 정적 사이트의 배포 방식과 표시 방식을 사용자 지정할 수 있는 구성 옵션을 제공합니다. Pages 설정으로 다음 작업을 수행할 수 있습니다:

• 403 및 404 응답에 대한 사용자 지정 오류 페이지를 제공합니다.
• _redirects 파일로 URL 리다이렉트를 구성합니다.
• CI/CD 규칙을 사용해 원하는 브랜치에서 페이지를 배포합니다.
• 미리 압축한 자산을 제공해 페이지 로드 속도를 높입니다.
• 사이트를 게시할 폴더를 사용자 지정합니다.
• 사이트의 고유 도메인을 생성하고 관리합니다.

Pages 소개는 GitLab Pages를 참고합니다.

GitLab Pages 요구 사항#

요약하면 GitLab Pages에 웹사이트를 업로드하는 데 필요한 것은 다음과 같습니다:

1. 인스턴스의 도메인: GitLab Pages에 사용되는 도메인 이름입니다 (관리자에게 문의합니다).
2. GitLab CI/CD: 리포지터리 루트 디렉터리에 pages라는 특정 job 이 포함된 .gitlab-ci.yml 파일입니다.
3. 프로젝트에 켜져 있는 GitLab Runner 입니다.

GitLab.com의 GitLab Pages#

웹사이트 호스팅에 GitLab.com의 GitLab Pages를 사용한다면 다음이 적용됩니다:

• GitLab.com의 GitLab Pages 도메인 이름은 gitlab.io 입니다.
• 사용자 지정 도메인과 TLS를 지원합니다.
• 인스턴스 러너가 기본적으로 켜져 있어 무료로 제공되며 웹사이트를 빌드하는 데 사용할 수 있습니다. 필요하면 자체 러너를 사용할 수도 있습니다.

예시 프로젝트#

예시 프로젝트 전체 목록은 GitLab Pages 그룹에서 확인합니다. 기여는 언제든 환영합니다.

사용자 지정 오류 코드 페이지#

public/ 디렉터리 루트에 403.html과 404.html 파일을 만들어 자체 403, 404 오류 페이지를 제공할 수 있습니다. 일반적으로 이 위치는 프로젝트의 루트 디렉터리이지만, 정적 생성기 구성에 따라 달라질 수 있습니다.

404.html의 경우 상황에 따라 동작이 다릅니다. 예를 들면 다음과 같습니다:

• 프로젝트 Pages(/project-slug/ 아래에서 제공)를 사용하면서 /project-slug/non/existing_file에 접근하면 GitLab Pages는 먼저 /project-slug/404.html을, 그다음 /404.html을 제공하려고 시도합니다.
• 사용자 또는 그룹 Pages(/ 아래에서 제공)를 사용하면서 /non/existing_file에 접근하면 GitLab Pages는 /404.html을 제공하려고 시도합니다.
• 사용자 지정 도메인을 사용하면서 /non/existing_file에 접근하면 GitLab Pages는 /404.html만 제공하려고 시도합니다.

GitLab Pages의 리다이렉트#

_redirects 파일로 사이트의 리다이렉트를 구성할 수 있습니다. 자세한 내용은 GitLab Pages 리다이렉트 생성을 참고합니다.

Pages 사이트 삭제#

프로젝트의 모든 Pages 배포를 영구적으로 삭제합니다.

Pages를 삭제하려면 다음을 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. Domains & settings 탭을 선택합니다.
4. Delete Pages를 선택합니다.
5. 확인 대화 상자에서 Delete Pages를 선택합니다.

Pages 사이트가 더 이상 배포되지 않습니다. 이 Pages 사이트를 다시 배포하려면 새 파이프라인을 실행합니다.

서브도메인의 서브도메인#

GitLab 인스턴스의 최상위 도메인(*.example.io) 아래에서 Pages를 사용하면 서브도메인의 서브도메인에는 HTTPS를 사용할 수 없습니다. 네임스페이스나 그룹 이름에 점이 포함되어 있으면(예: foo.bar) https://foo.bar.example.io 도메인은 동작하지 않습니다.

이 제한은 HTTP Over TLS 프로토콜 때문입니다. HTTP를 HTTPS로 리다이렉트하지 않는 한 HTTP 페이지는 정상적으로 동작합니다.

프로젝트 및 그룹의 GitLab Pages#

GitLab Pages 웹사이트는 프로젝트에서 호스팅해야 합니다. 이 프로젝트는 비공개, 내부 공개, 공개 중 하나일 수 있으며 그룹이나 하위 그룹에 속할 수 있습니다.

그룹 웹사이트의 경우 해당 그룹은 하위 그룹이 아니라 최상위 그룹이어야 합니다.

프로젝트 웹사이트의 경우 프로젝트를 먼저 생성한 다음 http(s)://namespace.example.io/project-path에서 접근할 수 있습니다.

Pages에 대한 특정 구성 옵션#

특정 사용 사례에 맞게 GitLab CI/CD를 설정하는 방법을 설명합니다.

일반 HTML 웹사이트를 위한 .gitlab-ci.yml#

리포지터리에 다음 파일이 있다고 가정합니다:

├── index.html
├── css
│   └── main.css
└── js
    └── main.js

이때 아래 .gitlab-ci.yml 예시는 프로젝트 루트 디렉터리의 모든 파일을 public/ 디렉터리로 옮깁니다. .public 우회책은 cp가 public/을 자기 자신으로 무한히 복사하지 않도록 하기 위한 것입니다:

create-pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

위 YAML 예시는 사용자 정의 job 이름을 사용합니다.

정적 사이트 생성기를 위한 .gitlab-ci.yml#

단계별 가이드는 해당 문서를 참고합니다.

코드가 있는 리포지터리를 위한 .gitlab-ci.yml#

GitLab Pages는 기본적으로 브랜치·태그와 무관하며, 배포는 전적으로 .gitlab-ci.yml에 지정한 내용에 따라 결정됩니다. Pages 전용으로 사용하는 브랜치에 새 커밋이 푸시될 때만 pages job 이 실행되도록 rules:if로 제한할 수 있습니다.

이렇게 하면 프로젝트 코드는 main 브랜치에 두고, 고아 브랜치(여기서는 pages로 부릅니다)에서 정적 생성기 사이트를 호스팅할 수 있습니다.

다음과 같이 비어 있는 새 브랜치를 생성할 수 있습니다:

git checkout --orphan pages

이 새 브랜치에서 처음 만든 커밋에는 부모가 없으며, 다른 모든 브랜치·커밋과 완전히 분리된 새 히스토리의 루트가 됩니다. 정적 생성기의 소스 파일을 pages 브랜치에 푸시합니다.

아래는 .gitlab-ci.yml 사본이며, 가장 중요한 줄은 모든 작업을 pages 브랜치에서 실행하도록 지정한 마지막 줄입니다:

create-pages:
  image: ruby:2.6
  script:
    - gem install jekyll
    - jekyll build -d public/
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: '$CI_COMMIT_REF_NAME == "pages"'

main 브랜치에는 다른 파일이 있고 Jekyll의 소스 파일은 pages 브랜치에 있으며 이 브랜치에는 .gitlab-ci.yml도 포함된 예시를 확인합니다.

위 YAML 예시는 사용자 정의 job 이름을 사용합니다.

압축된 자산 제공#

대부분의 최신 브라우저는 압축 형식의 파일 다운로드를 지원합니다. 파일 크기를 줄여 다운로드 속도를 높입니다.

Pages는 압축되지 않은 파일을 제공하기 전에 같은 파일이 .br 또는 .gz 확장자로 존재하는지 확인합니다. 해당 파일이 있고 브라우저가 압축 파일 수신을 지원하면 압축되지 않은 파일 대신 그 버전을 제공합니다.

이 기능을 활용하려면 Pages에 업로드하는 아티팩트가 다음과 같은 구조여야 합니다:

public/
├─┬ index.html
│ | index.html.br
│ └ index.html.gz
│
├── css/
│   └─┬ main.css
│     | main.css.br
│     └ main.css.gz
│
└── js/
    └─┬ main.js
      | main.js.br
      └ main.js.gz

.gitlab-ci.yml의 pages job에 다음과 같은 script: 명령을 포함하면 이를 구현할 수 있습니다:

create-pages:
  # Other directives
  script:
    # Build the public/ directory first
    - find public -type f -regex '.*\.\(htm\|html\|xml\|txt\|text\|js\|css\|svg\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(htm\|html\|xml\|txt\|text\|js\|css\|svg\)$' -exec brotli -f -k {} \;
  pages: true  # specifies that this is a Pages job

파일을 미리 압축해 두 버전을 모두 아티팩트에 포함하면 Pages는 요청 시점에 파일을 압축하지 않고도 압축 콘텐츠와 비압축 콘텐츠 요청을 모두 처리할 수 있습니다.

위 YAML 예시는 사용자 정의 job 이름을 사용합니다.

모호한 URL 해결#

GitLab Pages는 확장자가 포함되지 않은 URL 요청을 받으면 어떤 파일을 제공할지 가정해 판단합니다.

다음 파일로 배포된 Pages 사이트를 가정합니다:

public/
├── index.html
├── data.html
├── info.html
├── data/
│   └── index.html
└── info/
    └── details.html

Pages는 이러한 파일 각각에 여러 URL로 접근할 수 있도록 지원합니다. 특히 URL 이 디렉터리만 지정하면 항상 index.html 파일을 찾습니다. URL 이 존재하지 않는 파일을 참조하더라도 URL에 .html을 붙였을 때 존재하는 파일이 되면 그 파일을 대신 제공합니다. 앞의 Pages 사이트에서 일어나는 동작의 예는 다음과 같습니다:

public/data/index.html 이 존재하면 /data와 /data/ URL 경로 모두에서 public/data.html 파일보다 우선합니다.

기본 폴더 사용자 지정#

히스토리

• GitLab 16.1에서 FF_CONFIGURABLE_ROOT_DIR이라는 Pages 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 16.1에서 GitLab.com에서 활성화되었습니다.
• GitLab 16.2에서 GitLab Self-Managed에서 활성화되었습니다.
• GitLab 17.9에서 publish 속성에 변수를 전달할 수 있도록 변경되었습니다.
• GitLab 17.9에서 publish 속성이 pages 키워드 아래로 이동되었습니다.
• GitLab 17.10에서 pages.publish 경로가 artifacts:paths에 자동으로 추가되었습니다.

기본적으로 Pages는 빌드 파일에서 public이라는 폴더를 찾아 게시합니다.

이 폴더 이름을 다른 값으로 바꾸려면 .gitlab-ci.yml의 deploy-pages job 구성에 pages.publish 속성을 추가합니다.

다음 예시는 dist라는 폴더를 대신 게시합니다:

create-pages:
  script:
    - npm run build
  pages:  # specifies that this is a Pages job
    publish: dist

위 YAML 예시는 사용자 정의 job 이름을 사용합니다.

pages.publish 필드에서 변수를 사용하는 방법은 pages.publish를 참고합니다.

Pages는 사이트 파일을 저장하는 데 아티팩트를 사용하므로 pages.publish의 값이 artifacts:paths에 자동으로 추가됩니다. 앞의 예시는 다음과 동일합니다:

create-pages:
  script:
    - npm run build
  pages:
    publish: dist
  artifacts:
    paths:
      - dist

GitLab Pages의 고유 도메인 재생성#

히스토리

• GitLab 17.7에서 도입되었습니다.

GitLab Pages 사이트의 고유 도메인을 다시 생성할 수 있습니다.

도메인을 다시 생성하면 이전 URL은 더 이상 동작하지 않습니다. 이전 URL로 접근하면 404 오류가 표시됩니다.

사전 요구 사항

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.
• 프로젝트의 Pages 설정에서 Use unique domain 설정이 켜져 있어야 합니다.

GitLab Pages 사이트의 고유 도메인을 다시 생성하려면 다음을 수행합니다.

1. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
2. Access pages 옆에서 Regenerate unique domain을 누릅니다.
3. GitLab 이 Pages 사이트의 새 고유 도메인을 생성합니다.

알려진 문제#

알려진 문제 목록은 GitLab 공개 이슈 트래커를 참고합니다.

문제 해결#

GitLab Pages 사이트 URL 접근 시 404 오류#

이 문제는 대부분 public 디렉터리에 index.html 파일이 없어서 발생합니다. Pages 사이트를 배포한 뒤 404가 발생하면 public 디렉터리에 index.html 파일이 있는지 확인합니다. 파일 이름이 test.html처럼 다르면 Pages 사이트에 접근할 수는 있지만 전체 경로가 필요합니다. 예: https://group-name.pages.example.com/project-slug/test.html.

public 디렉터리의 내용은 최신 파이프라인의 아티팩트를 탐색해 확인할 수 있습니다.

public 디렉터리 아래에 있는 파일은 프로젝트의 Pages URL로 접근할 수 있습니다.

404는 잘못된 권한과 관련이 있을 수도 있습니다. Pages 접근 제어가 켜져 있는 상태에서 사용자가 Pages URL로 이동했을 때 404 응답을 받는다면 해당 사용자에게 사이트를 볼 권한이 없을 수 있습니다. 이 경우 해당 사용자가 프로젝트의 멤버인지 확인합니다.

끊어진 상대 링크#

GitLab Pages는 확장자 없는 URL을 지원합니다. 다만 이슈 #354에서 설명한 문제 때문에 확장자 없는 URL 이 슬래시(/)로 끝나면 페이지의 상대 링크가 모두 깨집니다.

이 문제를 우회하려면 다음을 수행합니다.

• Pages 사이트를 가리키는 URL에 확장자를 포함하거나 끝에 슬래시를 붙이지 않습니다.
• 가능하다면 사이트에서 절대 URL만 사용합니다.

Safari에서 미디어 콘텐츠를 재생할 수 없음#

Safari에서 미디어 콘텐츠를 재생하려면 웹 서버가 Range 요청 헤더를 지원해야 합니다. GitLab Pages가 HTTP Range 요청을 처리하도록 하려면 .gitlab-ci.yml 파일에 다음 두 변수를 사용합니다:

create-pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "Deploying pages"
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  environment: production

FF_USE_FASTZIP 변수는 ARTIFACT_COMPRESSION_LEVEL에 필요한 기능 플래그를 켭니다.

위 YAML 예시는 사용자 정의 job 이름을 사용합니다.

여러 브라우저 탭에서 비공개 GitLab Pages 사이트 접근 시 401 오류#

사전 인증 없이 서로 다른 두 탭에서 비공개 Pages URL에 동시에 접근하면 각 탭에 서로 다른 state 값이 반환됩니다. 그러나 Pages 세션에는 해당 클라이언트에 대해 가장 최근의 state 값만 저장됩니다. 그 결과 자격 증명을 제출한 뒤 한 탭에서 401 Unauthorized 오류가 반환됩니다.

401 오류를 해결하려면 페이지를 새로 고칩니다.

pages:deploy job 실패#

GitLab Pages로 배포하려면 루트 콘텐츠 디렉터리에 비어 있지 않은 index.html 파일이 있어야 하며, 그렇지 않으면 pages:deploy job 이 실패합니다.

콘텐츠 디렉터리는 기본적으로 public/ 이며, .gitlab-ci.yml 파일의 pages.publish 키워드로 지정한 디렉터리를 사용할 수도 있습니다.