GitLab Pages 설정

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

이 문서는 GitLab 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 그룹을 방문하시기 바랍니다. 기여는 언제나 환영합니다.

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

403.html 및 404.html 파일을 public/ 디렉토리의 루트에 생성하여 고유한 403 및 404 오류 페이지를 제공할 수 있습니다. 일반적으로 이는 귀하의 프로젝트의 루트 디렉토리이지만, 정적 생성기 설정에 따라 다를 수 있습니다.

404.html의 경우, 다양한 시나리오가 있습니다. 예를 들어:

  • 프로젝트 페이지( /project-slug/ 하위에서 제공)를 사용하고 /project-slug/non/existing_file에 액세스하려고 하는 경우, GitLab Pages는 먼저 /project-slug/404.html, 그 후 /404.html를 제공하려고 합니다.
  • 사용자 또는 그룹 페이지(/ 하위에서 제공)를 사용하고 /non/existing_file에 액세스하려고 하는 경우, GitLab Pages는 /404.html를 제공하려고 합니다.
  • 사용자 정의 도메인을 사용하고 /non/existing_file에 액세스하려고 하는 경우, GitLab Pages는 /404.html만 제공하려고 합니다.

GitLab Pages의 리디렉션

_redirects 파일을 사용하여 사이트의 리디렉션을 구성할 수 있습니다. 자세한 내용은 GitLab Pages를 위한 리디렉션 생성을 참조하십시오.

페이지 제거

페이지를 제거하려면:

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

하위 도메인의 하위 도메인

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

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

프로젝트 및 그룹의 GitLab Pages

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

그룹 웹사이트의 경우, 그룹은 최상위에 있어야 하며 하위그룹이 아니어야 합니다.

프로젝트 웹사이트의 경우, 먼저 프로젝트를 만들고 http(s)://namespace.example.io/project-path에서 액세스할 수 있습니다.

고유 도메인 활성화

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

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

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

Pages에 대한 특정 구성 옵션

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

.gitlab-ci.yml : 일반 HTML 웹사이트용

저장소에 다음 파일이 포함되어 있는 경우: 

├── 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에서 지정한 것에만 의존합니다. 특정하게 사용하는 브랜치에 새 커밋이 푸시될 때마다 pages 작업을 제한할 수 있습니다.

이렇게 하면 프로젝트 코드가 main 브랜치에 있고 고립된 브랜치(이름을 pages로 지정)를 사용하여 정적 생성기 사이트를 호스팅할 수 있습니다.

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

git checkout --orphan pages

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

아래는 가장 중요한 줄이 마지막 줄로 지정되어 pages 브랜치에서 모든 것을 실행하도록 하는 .gitlab-ci.yml의 복사본입니다: 

image: ruby:2.6

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

이 예제는 main 브랜치와 Jekyll의 소스 파일이 포함된 pages 브랜치를 보여줍니다.

압축된 에셋 제공

대부분의 현대 브라우저는 압축 형식으로 파일을 다운로드하는 것을 지원합니다. 이렇게 하면 파일 크기가 줄어들어 다운로드 속도가 빨라집니다.

압축되지 않은 파일을 제공하기 전에 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의 pages 작업에 다음과 같은 명령어를 포함하여야 합니다: 

pages:
  # Other directives
  script:
    # Build the public/ directory first
    - 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

기본 폴더 사용자 정의

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

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

다음 예제는 dist라는 이름의 폴더를 게시하는 방법입니다: 

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

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

알려진 문제

알려진 문제의 목록은 GitLab 공개 이슈 트래커를 참조하세요.

문제 해결

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

이 문제는 공개 디렉터리에 index.html 파일이 없어서 발생했을 가능성이 가장 높습니다. Pages 사이트를 배포한 후 404 오류가 발생하면 공개 디렉터리에 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 요청 헤더를 지원해야합니다. GitLab Pages가 HTTP Range 요청을 제공하려면 .gitlab-ci.yml 파일에 다음 두 변수를 사용해야 합니다: 

pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "Deploying pages"
  artifacts:
    paths:
      - public
  environment: production

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