GitLab 페이지 설정

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

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

우선 GitLab Pages에 대해 익숙해지려면:

GitLab 페이지 요구 사항

간단히 말해서, GitLab Pages에 웹사이트를 업로드하기 위해 필요한 것은 다음과 같습니다:

  1. 인스턴스의 도메인: GitLab Pages에 사용되는 도메인 이름 (관리자에게 문의하세요).
  2. GitLab CI/CD: 리포지토리의 루트 디렉토리에 특정 작업인 pages가 포함된 .gitlab-ci.yml 파일.
  3. 프로젝트용으로 활성화된 GitLab Runner.

GitLab.com의 GitLab 페이지

만약 귀하의 웹사이트를 호스팅하기 위해 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. 배포 > 페이지를 선택합니다.
  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에서 액세스할 수 있습니다.

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 브랜치에 두고 정적 생성기 사이트를 호스트하기 위해 고립된 브랜치(이름을 pages로 지정)를 사용할 수 있습니다.

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

git checkout --orphan 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 브랜치 및 .gitlab-ci.yml의 예시를 참조하세요.

압축된 에셋 제공

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

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

이 기능을 활용하기 위해서는 업로드하는 아티팩트가 다음 구조를 가져야 합니다:

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

파일을 미리 압축하고 아티팩트에 두 가지 버전을 포함시킴으로써, Pages는 파일을 요청받을 때 압축 및 압축 해제 과정 없이 두 가지 형식으로 모두 제공할 수 있습니다.

모호한 URL 해결

GitLab Pages는 확장자를 포함하지 않은 URL에 대한 파일 제공에 관한 가정을 합니다.

다음과 같이 배포된 페이지 사이트를 고려해보세요:

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에서 셀프 매니지드에서 활성화됨.

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

다른 값을 사용하려면 .gitlab-ci.yml의 pages 작업 구성에 publish 속성을 추가하세요.

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

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

public이라는 이름의 폴더가 아닌 다른 이름의 폴더를 사용하는 경우, 아티팩트로서와 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 Access Control이 활성화된 경우, Pages URL에 이동하고 404 응답을 받는 경우, 사용자가 사이트를 볼 수 있는 권한을 가지고 있지 않을 수 있습니다. 이를 해결하려면 사용자가 프로젝트 멤버임을 확인하세요.

깨진 상대적 링크

GitLab Pages는 확장자 없는 URL을 지원합니다. 그러나 이슈 #354에 설명된 문제로, 확장자 없는 URL이 슬래시(/)로 끝나는 경우 페이지의 상대적 링크가 깨집니다.

이 문제를 해결하기 위해:

  • Pages 사이트를 가리키는 URL에 확장자가 포함되거나 슬래시를 포함하지 않도록 확인하세요.
  • 가능한 경우 사이트에서 절대적 URL만 사용하세요.

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

Safari는 미디어 콘텐츠를 재생하기 위해 웹 서버가 범위 요청 헤더를 지원해야 합니다. GitLab Pages가 HTTP 범위 요청을 제공하려면 .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에 필요한 기능 플래그를 활성화합니다.