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 및 404 오류 페이지를 제공하려면 public/ 디렉토리의 루트에 403.html 및 404.html 파일을 생성하세요. 일반적으로 이는 프로젝트의 루트 디렉터리이지만, 정적 생성기 설정에 따라 다를 수 있습니다.

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. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Deploy > Pages를 선택합니다.
  3. Remove pages를 선택합니다.

서브도메인의 서브도메인

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

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

GitLab Pages 프로젝트 및 그룹에서

GitLab Pages 웹사이트는 프로젝트에서 호스팅해야 합니다. 이 프로젝트는
비공개, 내부 또는 공개일 수 있으며
group 또는 subgroup에 속할 수 있습니다.

group websites의 경우,
그룹은 최상위 수준에 있어야 하며 하위 그룹이 아니어야 합니다.

project websites의 경우,
먼저 프로젝트를 생성하고 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/를 무한 루프로 복사하지 않도록 하기 위해서입니다:

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 작업을 rules:if로 제한할 수 있으며,
이는 페이지에 특별히 사용되는 브랜치에 새 커밋이 푸시될 때마다 가능합니다.

이렇게 하면, 프로젝트의 코드를 main 브랜치에 두고
정적 생성기 사이트를 호스팅하기 위해 오르phan 브랜치(예를 들어 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 브랜치와
Jekyll의 소스 파일이 포함된 pages 브랜치
의 예를 참고하세요. 이 브랜치에도 .gitlab-ci.yml이 포함되어 있습니다.

압축된 자산 제공

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

압축되지 않은 파일을 제공하기 전에, 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: 명령을 포함하세요:

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 {} \;

파일을 사전 압축하고 두 버전을 모두 아티팩트에 포함시킴으로써,
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 파일보다 우선합니다.

기본 폴더 사용자 정의

기본적으로, 아티팩트 폴더는 사이트의 정적 파일을 포함하며 public이라는 이름이어야 합니다.

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

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

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

public이 아닌 다른 폴더 이름을 사용하는 경우, Page를 배포할 디렉토리를 아티팩트와 publish 속성 모두로 지정해야 합니다. 둘 다 필요한 이유는 여러 경로를 아티팩트로 정의할 수 있기 때문에, 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.

공용 디렉토리의 내용은 아티팩트 브라우징을 통해 최신 파이프라인에서 확인할 수 있습니다.

공용 디렉토리에 나열된 파일은 프로젝트의 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 파일에 다음 두 변수를 사용해야 합니다:

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에 필요한 기능 플래그를 활성화합니다.