GitLab Pages 설정

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

이 문서는 GitLab Pages가 제공하는 옵션과 설정을 탐색하기 위한 사용자 가이드입니다.

먼저 GitLab Pages에 익숙해지려면:

  • GitLab Pages 소개를 읽어보세요.
  • Pages 시작 방법을 배워보세요.
  • 귀하의 GitLab 인스턴스 전체에서 GitLab Pages를 활성화하는 방법에 대해 관리자 문서에서 알아보세요(../../../administration/pages/index.md).

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 그룹을 방문하세요. 기여는 언제나 환영입니다.

커스텀 에러 코드 페이지

403.html 및 404.html 파일을 public/ 디렉터리의 루트에 생성하여 고유의 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를 위한 리디렉션 생성을 참조하세요.

페이지 제거하기

웹페이지를 제거하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > 페이지를 선택합니다.
  3. 페이지 제거를 선택합니다.

서브도메인

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에서 액세스할 수 있습니다.

고유 도메인 활성화

기본적으로 그룹의 모든 프로젝트가 동일한 도메인, 즉 group.gitlab.io를 공유합니다. 이는 그룹의 모든 프로젝트에 대해 쿠키도 공유된다는 의미입니다.

프로젝트에서 고유 Pages 도메인을 사용하도록 보장하려면 다음과 같이 프로젝트에 대해 고유 도메인 기능을 활성화하세요:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > 페이지를 선택합니다.
  3. 고유 도메인 사용 확인란을 선택합니다.
  4. 변경 사항 저장을 선택합니다.

Pages의 특정 구성 옵션

특정 사용 사례에 대해 GitLab CI/CD를 설정하는 방법을 알아보세요.

평범한 HTML 웹사이트를 위한 .gitlab-ci.yml

이 리포지터리에 다음과 같은 파일이 포함되어 있다고 가정합니다: 

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

그러면 아래의 .gitlab-ci.yml 예제는 프로젝트의 루트 디렉터리의 모든 파일을 public/ 디렉터리로 이동합니다. .public의 임시적인 해결책은 cp가 무한 루프에서 public/을 자기 자신에게 복사하지 않도록 하는 것입니다: 

pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

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

단계별 가이드를 참조하세요.

코드가 포함된 리포지터리를 위한 .gitlab-ci.yml

GitLab Pages는 기본적으로 브랜치/태그에 구애받지 않으며 배포는 오로지 .gitlab-ci.yml에서 지정하는 대로만 이루어집니다. 특정 페이지용으로 사용하는 브랜치에 새 커밋이 푸시될 때마다 rules:if로 pages 작업을 제한할 수 있습니다.

이렇게 하면 main 브랜치에 프로젝트 코드를 둔 채로 고립된 브랜치(여기서는 pages라고 명명함)를 만들어 정적 생성기 사이트를 호스트할 수 있습니다.

다음과 같이 새로운 빈 브랜치를 만들 수 있습니다: 

git checkout --orphan pages

이 새로운 브랜치에 만든 첫 커밋은 부모가 없으며 모든 다른 브랜치와 커밋에서 완전히 분리된 새로운 히스토리의 루트입니다. 정적 생성기의 소스 파일을 pages 브랜치에 푸시하세요.

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

image: ruby:2.6

pages:
  script:
    - gem install jekyll
    - jekyll build -d public/
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_REF_NAME == "pages"'

main 브랜치에 다른 파일이 있는 예시 및 소스 파일이 있는 pages 브랜치를 참조하세요. 또한 중요한 .gitlab-ci.yml도 포함되어 있습니다.

압축된 에셋 제공

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

압축되지 않은 파일을 제공하기 전에 Pages는 동일한 파일이 .br 또는 .gz 확장자로 존재하는지 확인합니다. 그리고 브라우저가 압축 파일을 받아들일 수 있는 경우, 압축 해제된 것 대신 해당 버전을 제공합니다.

이 기능을 활용하려면 Pages에 업로드하는 artifact는 다음 구조여야 합니다: 

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 페이지 작업에 다음과 같은 script: 명령을 포함하면 됩니다: 

pages:
  # 다른 지시문
  script:
    # public/ 디렉터리 먼저 빌드
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec brotli -f -k {} \;

파일을 미리 압축한 후 artifact에 두 버전을 포함시킴으로써, Pages는 압축 및 압축 해제 파일을 요청할 때 필요할 때마다 압축을 할 필요 없이 제공할 수 있습니다.

모호한 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 사이트를 가정했을 때 어떻게 작동하는지에 대한 예시 몇 가지를 보여드리겠습니다:

URL 경로 HTTP 응답
/ 200 OK: public/index.html
/index.html 200 OK: public/index.html
/index 200 OK: public/index.html
/data 302 Found: /data/로 리디렉션
/data/ 200 OK: public/data/index.html
/data.html 200 OK: public/data.html
/info 302 Found: /info/로 리디렉션
/info/ 404 Not Found 오류 페이지
/info.html 200 OK: public/info.html
/info/details 200 OK: public/info/details.html
/info/details.html 200 OK: public/info/details.html

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에서 Self-managed에서 활성화됨.

기본적으로 사이트의 정적 파일을 포함하는 artifact 폴더의 이름은 public이어야 합니다.

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

다음 예시는 dist라는 이름의 폴더를 게시하는 방법을 보여줍니다: 

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

public이 아닌 다른 폴더 이름을 사용하는 경우, artifact로 배포할 디렉터리를 지정해야 하며, publish 속성 아래에도 지정해야 합니다. 이 두 가지를 모두 지정해야 하는 이유는 여러 경로를 artifact로 정의할 수 있으며, GitLab은 어떤 것을 배포할지 모르기 때문입니다.

알려진 문제점

알려진 문제점 디렉터리은 GitLab public issue tracker에서 확인할 수 있습니다.

문제 해결

GitLab Pages 사이트 URL에 액세스할 때 404 오류

이 문제는 공개 디렉터리에 index.html 파일이 누락됨으로 인해 발생하는 가능성이 가장 높습니다. Pages 사이트를 배포한 후 404 오류가 발생한 경우, public 디렉터리에 index.html 파일이 있는지 확인하십시오. test.html과 같이 다른 이름의 파일이 포함되어 있는 경우에도 Pages 사이트에는 액세스할 수 있지만 전체 경로가 필요합니다. 예: https//group-name.pages.example.com/project-slug/test.html.

최신 파이프라인에서 artifact를 둘러보는 내용을 확인할 수 있습니다.

공개 디렉터리에 나열된 파일은 프로젝트의 Pages URL을 통해 액세스할 수 있습니다.

404 오류는 권한 설정과 관련이 있을 수 있습니다. Pages Access Control이 활성화되어 있고 사용자가 Pages URL로 이동한 후 404 오류가 발생하는 경우, 사용자가 사이트를 볼 수 있는 권한이 없을 수 있습니다. 이를 해결하려면 사용자가 프로젝트의 구성원인지 확인하십시오.

상대적 링크가 작동하지 않음

GitLab Pages는 확장명이 없는 URL을 지원합니다. 그러나 이슈 #354에서 설명한 문제로 인해 확장명이 없는 URL이 슬래시(/)로 끝나면 페이지의 상대적 링크가 손상됩니다.

이 문제를 해결하려면:

  • Pages 사이트를 가리키는 URL에 확장명이 포함되어 있거나 슬래시로 끝나지 않도록 합니다.
  • 가능하다면 사이트에서는 절대 URL만 사용합니다.

Safari에서 미디어 콘텐츠 재생 불가

Safari는 미디어 콘텐츠를 재생하려면 웹 서버가 범위 요청 헤더(Range request header)를 지원해야 합니다. GitLab Pages에서 HTTP 범위 요청을 제공하려면 .gitlab-ci.yml 파일에 다음 두 변수를 사용해야 합니다: 

pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "페이지 배포 중"
  artifacts:
    paths:
      - public
  environment: production

FF_USE_FASTZIP 변수는 ARTIFACT_COMPRESSION_LEVEL에 필요한 피처 플래그를 활성화합니다.