GitLab Pages

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

GitLab Pages를 사용하면 GitLab의 저장소에서 정적 웹사이트를 직접 발행할 수 있습니다.

  • 개인 또는 비즈니스 웹사이트에 사용할 수 있습니다.
  • 정적 사이트 생성기(SSG) 또는 일반 HTML을 사용할 수 있습니다.
  • 프로젝트, 그룹 또는 사용자 계정을 위한 웹사이트를 생성할 수 있습니다.
  • 무료로 자체 GitLab 인스턴스나 GitLab.com에 사이트를 호스팅할 수 있습니다.
  • 사용자 정의 도메인 및 TLS 인증서를 연결할 수 있습니다.
  • 콘텐츠에 라이선스를 지정할 수 있습니다.
Pages에서 지원하는 SSG 예시

Pages를 사용하여 웹사이트를 발행하려면 Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo 또는 Brunch와 같은 정적 사이트 생성기를 사용할 수 있습니다. 또한 순수 HTML, CSS 및 JavaScript로 직접 작성된 웹사이트도 발행할 수 있습니다.

Pages는 .php 및 .asp와 같은 동적 서버 측 처리를 지원하지 않습니다. 자세한 정보는 정적 대 동적 웹사이트를 참조하세요.

시작하기

GitLab Pages 웹사이트를 만들려면 다음을 수행하세요:

문서 설명
.gitlab-ci.yml을 사용하여 GitLab UI로 간단한 웹사이트 만들기 기존 프로젝트에 Pages 사이트 추가. UI를 사용하여 간단한 .gitlab-ci.yml을 설정하세요.
.gitlab-ci.yml 파일을 처음부터 만들기 기존 프로젝트에 Pages 사이트 추가. 직접 CI 파일을 생성하고 구성하는 방법을 배웁니다.
.gitlab-ci.yml 템플릿 사용하기 기존 프로젝트에 Pages 사이트 추가. 사전 작성된 CI 템플릿 파일을 사용하세요.
샘플 프로젝트 포크하기 샘플 프로젝트를 포크하여 이미 구성된 Pages로 새 프로젝트를 만드세요.
프로젝트 템플릿 사용하기 템플릿을 사용하여 이미 구성된 Pages로 새 프로젝트를 만드세요.

GitLab Pages 웹사이트를 업데이트하려면 다음을 수행하세요:

문서 설명
GitLab Pages 도메인 이름, URL 및 기본 URL GitLab Pages의 기본 도메인에 대해 알아보세요.
GitLab Pages 살펴보기 요구 사항, 기술적 측면, 특정 GitLab CI/CD 구성 옵션, 액세스 제어, 사용자 정의 404 페이지, 제한 사항 및 FAQ에 대해 알아봅니다.
사용자 정의 도메인 및 SSL/TLS 인증서 사용자 정의 도메인 및 하위 도메인, DNS 레코드 및 SSL/TLS 인증서.
Let’s Encrypt 통합 GitLab에서 자동으로 획득하고 갱신되는 Let’s Encrypt 인증서로 Pages 사이트를 보안하세요.
리다이렉션 다른 페이지로 전달하기 위한 HTTP 리디렉션 설정.

더 많은 정보는 다음을 참조하세요:

문서 설명
정적 대 동적 웹사이트 정적 대 동적 사이트 개요.
현대적 정적 사이트 생성기 SSG 개요.
GitLab Pages를 사용하여 모든 SSG 사이트 빌드 GitLab Pages에 SSG 사용.

작동 방식

GitLab Pages를 사용하려면 GitLab에서 웹사이트 파일을 업로드할 프로젝트를 만들어야 합니다. 이러한 프로젝트는 공개, 내부 또는 비공개일 수 있습니다.

GitLab은 항상 리포지토리의 public라는 특정 폴더에서 웹사이트를 배포합니다. GitLab에서 새 프로젝트를 만들면 리포지토리가 자동으로 사용할 수 있습니다.

GitLab은 내장 도구인 GitLab CI/CD를 사용하여 웹사이트를 빌드하고 GitLab Pages 서버에 게시합니다. 이 작업을 수행하기 위해 GitLab CI/CD가 실행하는 일련의 스크립트는 .gitlab-ci.yml이라는 파일에서 생성됩니다. 본인이 만들고 수정할 수 있는 구성 파일에서 pages라는 특정 job은 GitLab에게 GitLab Pages 웹사이트를 배포하고 있다는 것을 알립니다.

GitLab Pages 웹사이트의 기본 도메인인 *.gitlab.io나 본인의 도메인(example.com) 중 하나를 선택할 수 있습니다. 후자의 경우 도메인의 등록기(또는 제어판)에서 관리자 권한이 있어야 설정할 수 있습니다.

다음 다이어그램은 Pages를 시작하는 데 따를 수 있는 워크플로우를 보여줍니다.

GitLab Pages를 위한 새 프로젝트

Pages 사이트 액세스

GitLab Pages 기본 도메인(.gitlab.io)을 사용하는 경우 웹사이트가 자동으로 HTTPS로 안전하게 제공됩니다. 사용자 정의 도메인을 사용하는 경우 SSL/TLS 인증서로 웹사이트를 안전하게 할 수 있습니다.

GitLab.com을 사용하는 경우 웹사이트는 인터넷에 공개되어 있습니다. 웹사이트 액세스를 제한하려면 GitLab Pages 액세스 제어를 활성화하세요.

자체 관리 인스턴스를 사용하는 경우 웹사이트는 시스템 관리자가 선택한 Pages 설정에 따라 독자적으로 게시됩니다. 이 설정에 따라 공개 또는 내부로 설정할 수 있습니다.

페이지 예제

이러한 GitLab Pages 웹사이트 예제는 고급 기술을 배우고 사용자의 필요에 맞게 적응하는 데 도움이 될 수 있습니다:

자체 관리 GitLab Pages 관리

GitLab의 자체 관리 인스턴스를 실행 중이라면, 관리 단계를 따라 Pages를 구성하세요.

비디오 튜토리얼을 시청하여 GitLab Pages 관리 시작 방법을 알아보세요.

Helm Chart(Kubernetes) 인스턴스에서 GitLab Pages 구성

Helm 차트(Kubernetes)를 통해 배포된 인스턴스에서 GitLab Pages를 구성하려면 다음을 사용하세요:

GitLab Pages 보안

.을 포함하는 이름 공간

사용자 이름이 example인 경우 GitLab Pages 웹사이트는 example.gitlab.io에 위치합니다. GitLab은 사용자 이름에 .을 포함할 수 있으므로 bar.example라는 사용자는 bar.example.gitlab.io라는 GitLab Pages 웹사이트를 만들 수 있으며, 이는 실제로 example.gitlab.io 웹사이트의 하위 도메인입니다. 웹사이트에 대해 JavaScript를 사용하여 쿠키를 설정하는 경우 주의해야 합니다. JavaScript로 수동으로 쿠키를 설정하는 안전한 방법은 domain을 전혀 지정하지 않는 것입니다: 

// 안전함: 이 쿠키는 example.gitlab.io에서만 보입니다
document.cookie = "key=value";

// 안전하지 않음: 이 쿠키는 example.gitlab.io 및 해당 하위 도메인에 모두 표시됩니다.
// 선행 점의 존재 여부에 관계없이
document.cookie = "key=value;domain=.example.gitlab.io";
document.cookie = "key=value;domain=example.gitlab.io";

이 문제는 사용자 지정 도메인을 사용하거나 JavaScript로 수동으로 쿠키를 설정하지 않는 사용자에게는 영향을 주지 않습니다.

공유된 쿠키

기본적으로 그룹 내 모든 프로젝트는 group.gitlab.io와 같은 도메인을 공유합니다. 즉, 그룹의 모든 프로젝트에서 쿠키도 공유됩니다.

각 프로젝트가 다른 쿠키를 사용하도록 하려면 프로젝트에 대해 Pages 고유 도메인 기능을 활성화하세요.

고유 도메인

  • GitLab 15.9에서 도입됨 (기능 플래그 이름 pages_unique_domain 사용). 기본 설정 비활성화.
  • 기본으로 활성화 된 GitLab 15.11에서.
  • GitLab 16.3에서 기능 플래그 삭제.
  • GitLab 17.4에서 고유 도메인 URL을 더 짧게 변경.

기본적으로 모든 새 프로젝트에는 고유 도메인이 사용됩니다. 이는 동일한 그룹의 프로젝트가 쿠키를 공유하지 않도록 합니다.

프로젝트 관리자는 다음에서이 기능을 비활성화할 수 있습니다:

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

예 URL을 보려면 GitLab Pages 기본 도메인 이름을 참조하세요.

만료된 배포

자세히: 티어: 프리미엄, 얼티메이트 오퍼링: GitLab.com, 자체 관리, GitLab 전용

Pages 배포를 pages.expire_in에서 지정된 기간이 경과한 후 자동으로 삭제하도록 구성할 수 있습니다: 

pages:
  stage: deploy
  script:
    - ...
  pages:
    expire_in: 1 week
  artifacts:
    paths:
      - public

기본적으로 병렬 배포는 24시간 후에 자동으로 만료됩니다. 이 동작을 비활성화하려면 pages.expire_in을 never로 설정하세요.

만료된 배포는 10분마다 실행되는 크론 작업에 의해 중단됩니다. 중단된 배포는 이후 10분마다 실행되는 다른 크론 작업에 의해 삭제됩니다. 이를 복구하려면 중단된 배포 복구에서 설명된 단계를 따릅니다.

중단되거나 삭제된 배포는 더 이상 웹에서 사용할 수 없습니다. 사용자는 이와 같은 URL 구성으로 다른 배포가 생성될 때까지 해당 URL에서 404 찾을 수 없음 오류 페이지를 보게 됩니다.

중단된 배포 복구

전제 조건:

  • 해당 프로젝트에 대해 적어도 Maintainer 역할이 있어야 합니다.

아직 삭제되지 않은 중단된 배포를 복구하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동를 선택한 후 프로젝트를 찾으세요.
  2. 배포 > Pages를 선택하세요.
  3. 배포 포함 옆에있는 중단된 배포 포함 토글을 켭니다. 중단된 배포가 아직 삭제되지 않았다면 목록에 포함됩니다.
  4. 복구하려는 배포를 확장하고 복구를 선택합니다.

병렬 배포

Tier: 프리미엄, 얼티밋 Offering: GitLab.com, Self-managed, GitLab Dedicated Status: 베타
이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 정보는 이력을 참조하세요. 이 기능은 테스트용으로 제공되지만 프로덕션 사용 준비가 되지는 않았습니다.

GitLab Pages URL에 접두어를 구성하려면 pages.path_prefix CI/CD 옵션을 사용하십시오. 접두어를 사용하면 다음과 같이 여러 GitLab Pages 배포를 구분할 수 있습니다.

  • 기본 배포: 빈 path_prefix로 생성된 Pages 배포.
  • 병렬 배포: 빈 path_prefix가 아닌 값으로 생성된 Pages 배포.

pages.path_prefix의 값은 다음과 같습니다.

  • 모두 소문자로 변환됩니다.
  • 63바이트로 줄입니다.
  • 숫자(0-9)와 알파벳(a-z)을 제외한 모든 문자는 하이픈(-)으로 대체됩니다.
  • 선행 및 후행 하이픈(-)이 제거됩니다.

구성 예

https://gitlab.example.com/namespace/project와 같은 프로젝트를 고려해보겠습니다. 기본적으로 해당 프로젝트의 메인 Pages 배포는 다음을 통해 액세스할 수 있습니다.

  • 고유한 도메인을 사용하는 경우: https://project-namespace-123456.gitlab.io/.
  • 고유 도메인을 사용하지 않는 경우: https://namespace.gitlab.io/project.

pages.path_prefix가 프로젝트 브랜치 이름으로 구성되어 있고 username/testing_feature라는 브랜치가 있으면, 병렬 Pages 배포는 다음을 통해 액세스할 수 있습니다.

  • 고유한 도메인을 사용하는 경우: https://project-namespace-123456.gitlab.io/username-testing-feature.
  • 고유 도메인을 사용하지 않는 경우: https://namespace.gitlab.io/project/username-testing-feature.

병렬 배포 활성화

병렬 GitLab Pages 배포를 활성화하려면 다음을 수행하십시오:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > Pages를 선택합니다.
  3. 병렬 배포 활성화를 선택합니다.

제한

병렬 배포 수는 루트 수준 네임스페이스에 의해 제한됩니다. 특정 제한 사항은 다음을 참조하십시오:

네임스페이스의 활성 배포 수를 즉시 줄이려면 일부 배포를 삭제하십시오. 자세한 내용은 배포 삭제를 참조하세요.

자동으로 삭제할 구식 배포를 구성하려면 만료 배포를 참조하세요.

만료

기본적으로 병렬 배포는 24시간 후에 만료되어 삭제됩니다. 자체 호스팅된 인스턴스를 사용하는 경우 인스턴스 관리자가 다른 기본 기간을 구성할 수 있습니다.

만료 시간을 사용자 정의하려면 pages.expire_in을 구성하십시오.

배포가 자동으로 만료되지 않도록 하려면 pages.expire_in을 never로 설정하십시오.

경로 충돌

pages.path_prefix는 기존 사이트의 경로와 충돌을 일으킬 수 있는 CI/CD 변수에서 동적 값으로 가져올 수 있습니다. 예를 들어, 다음과 같은 기존 GitLab Pages 사이트가 있는 경우: 

/index.html
/documents/index.html

pages.path_prefix가 documents이면 해당 버전이 기존 경로를 덮어씁니다. 즉, 기존 사이트의 documents 배포의 /index.html 말고도 main 사이트의 documents/index.html를 가리킵니다.

CI/CD 변수를 다른 문자열과 혼합하면 경로 충돌 가능성이 감소합니다. 예를 들어: 

pages:
  stage: deploy
  script:
    - echo "${CI_PAGES_URL}/${PAGES_PREFIX}"을 통해 Pages 접근 가능
  variables:
    PAGES_PREFIX: "" # 기본적으로 접두사 없음 (마스터)
  pages:
    path_prefix: "$PAGES_PREFIX"
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 기본 브랜치에서 실행 (기본 PAGES_PREFIX)
    - if: $CI_COMMIT_BRANCH == "staging" # 마스터에서 실행 (기본 PAGES_PREFIX)
      variables:
        PAGES_PREFIX: '_stg' # 스테이징 브랜치에 _stg로 접두사 설정
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # MR용 접두사 조건부로 변경
      when: manual # MR용 Pages 수동 실행
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # `mr-123`과 같은 MR용 접두사 설정

동적 접두사를 위한 변수와 문자열을 혼합하는 몇 가지 예시:

  • pages.path_prefix: 'mr-$CI_COMMIT_REF_SLUG': mr-branch-name과 같이 브랜치 또는 태그 이름에 접두어를 붙입니다.
  • pages.path_prefix: '_${CI_MERGE_REQUEST_IID}_': MR 번호에 _를 접두사와 접미사로 붙입니다. _123_과 같이 MR 번호에 접두사와 접미사를 붙입니다.

병렬 배포를 사용하여 Pages 환경 생성

병렬 GitLab Pages 배포를 사용하여 새로운 환경을 생성할 수 있습니다. 예를 들어: 

pages:
  stage: deploy
  script:
    - "${CI_PAGES_URL}/${PAGES_PREFIX}"을 통해 Pages 접근 가능
  variables:
    PAGES_PREFIX: "" # 기본적으로 접두사 없음 (마스터)
  pages:
    path_prefix: "$PAGES_PREFIX"
  environment:
    name: "Pages ${PAGES_PREFIX}"
    url: "${CI_PAGES_URL}/${PAGES_PREFIX}"
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_BRANCH == "staging" # 기본 PAGES_PREFIX로 실행되도록 함 (마스터)
      variables:
        PAGES_PREFIX: '_stg' # 스테이징 브랜치에 _stg로 접두사 설정
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # MR에 대해 접두사 조건부로 변경
      when: manual # MR용 Pages 수동 실행
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # `mr-123`과 같이 MR용 접두사 설정

이 구성을 사용하면 사용자는 UI를 통해 각 GitLab Pages 배포에 액세스할 수 있습니다. Pages에 대한 환경을 사용하면 모든 Pages 환경이 프로젝트 환경 목록에 나열됩니다.

또한 유사한 환경을 그룹화할 수 있습니다.

배포 삭제

배포를 삭제하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > 페이지를 선택합니다.
  3. 배포 아래에서 삭제하려는 배포 영역을 선택합니다. 배포 세부 정보가 확장됩니다.
  4. 삭제를 선택합니다.

삭제를 선택하면 배포가 즉시 중지됩니다. 중지된 배포는 10분마다 실행되는 cron 작업에 의해 삭제됩니다.

아직 삭제되지 않은 중지된 배포를 복원하려면 중지된 배포 복구를 참조하세요.

자동 정리

path_prefix가 있는 머지 리퀘스트로 생성된 병렬 페이지 배포는 머지 리퀘스트가 닫히거나 병합될 때 자동으로 삭제됩니다.

사용자 정의 작업 이름

  • 도입됨 in GitLab 17.5 with a flag customizable_pages_job_name, disabled by default.

과거에는 페이지 배포 작업의 이름을 트리거하기 위해 pages로 지정해야 했습니다. pages 설정으로 이제 더는 필요하지 않습니다.

어떤 작업에서도 페이지 배포를 트리거하려면 작업 정의에 pages 속성을 포함하십시오. 해시 또는 단순히 true로 설정할 수 있습니다. 

deploy-my-pages-site:
  stage: deploy
  script:
    - npm run build
  pages: true
  artifacts:
    paths:
    - public

이것도 작동합니다: 

deploy-pages-review-app:
  stage: deploy
  script:
    - npm run build
  pages:
    path_prefix: '/_staging'
  artifacts:
    paths:
    - public

pages 속성이 false로 설정된 pages 이름의 작업의 경우 배포가 트리거되지 않습니다. 

pages:
  pages: false