GitLab Pages는 정적 사이트의 배포 및 표시를 사용자 지정하는 구성 옵션을 제공합니다. Pages 설정을 사용하면 다음을 수행할 수 있습니다:

• 403 및 404 응답에 대한 사용자 정의 오류 페이지를 제공합니다.
• _redirects 파일을 통해 URL 리다이렉트를 구성합니다.
• CI/CD 규칙을 사용하여 모든 브랜치에서 Pages를 배포합니다.
• 더 빠른 페이지 로드를 위해 사전 압축된 자산을 제공합니다.
• 사이트가 게시되는 폴더를 사용자 정의합니다.
• 사이트의 고유 도메인을 생성하고 관리합니다.

이 가이드는 GitLab Pages 사이트에 사용할 수 있는 설정 및 구성 옵션을 설명합니다. Pages 소개는 GitLab Pages를 참조하세요.

GitLab Pages 요구 사항#

간략히 말하면, GitLab Pages에 웹사이트를 업로드하기 위해 필요한 것입니다:

1. 인스턴스의 도메인: GitLab Pages에 사용되는 도메인 이름(관리자에게 문의하세요).
2. GitLab CI/CD: 저장소 루트 디렉토리에 pages라는 특정 작업이 있는 .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. Delete pages를 선택합니다.

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

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

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

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

프로젝트 및 그룹의 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 예시는 사용자 정의 작업 이름을 사용합니다.

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

단계별 가이드를 위해 이 문서를 참조하세요.

코드가 있는 저장소를 위한 .gitlab-ci.yml#

GitLab Pages는 기본적으로 브랜치/태그에 관계없이 작동하며, 배포는 .gitlab-ci.yml에 지정한 내용에만 의존합니다. Pages용으로 특별히 사용되는 브랜치에 새 커밋이 푸시될 때마다 rules:if로 pages 작업을 제한할 수 있습니다.

이렇게 하면 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의 소스 파일이 .gitlab-ci.yml도 포함하는 pages 브랜치에 있는 예시를 참조하세요.

이전 YAML 예시는 사용자 정의 작업 이름을 사용합니다.

압축된 자산 제공#

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

압축되지 않은 파일을 제공하기 전에, 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 작업에서 다음과 같은 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 예시는 사용자 정의 작업 이름을 사용합니다.

모호한 URL 해결#

GitLab Pages는 확장자가 포함되지 않은 URL에 대한 요청을 받을 때 어떤 파일을 제공할지에 대해 가정합니다.

다음 파일로 배포된 Pages 사이트를 고려해보세요:

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

Pages는 여러 다른 URL을 통해 이러한 각 파일에 도달하는 것을 지원합니다. 특히 URL이 디렉토리만 지정하는 경우 항상 index.html 파일을 찾습니다. 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에서 pages 키워드 아래로 publish 속성이 이동됨.
• GitLab 17.10에서 artifacts:paths에 pages.publish 경로가 자동으로 추가됨.

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

해당 폴더 이름을 다른 값으로 변경하려면 .gitlab-ci.yml의 deploy-pages 작업 구성에 pages.publish 속성을 추가합니다.

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

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

이전 YAML 예시는 사용자 정의 작업 이름을 사용합니다.

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 request 헤더를 지원하도록 요구합니다. 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 예시는 사용자 정의 작업 이름을 사용합니다.

여러 브라우저 탭에서 비공개 GitLab Pages 사이트에 액세스할 때 401 오류#

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

401 오류를 해결하려면 페이지를 새로고침하세요.

pages:deploy 작업 실패#

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

콘텐츠 디렉토리는 기본적으로 public/이거나, .gitlab-ci.yml 파일의 pages.publish 키워드로 지정된 디렉토리입니다.