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가 필요합니다.

자세한 내용은 정적 vs 동적 웹사이트를 참조하세요.

시작하기

GitLab Pages 웹사이트를 만들려면:

문서 설명
GitLab UI를 사용하여 간단한 .gitlab-ci.yml 만들기 기존 프로젝트에 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 리디렉션을 설정합니다.

자세한 내용은 다음을 참조하세요:

문서 설명
정적 vs 동적 웹사이트 정적 사이트와 동적 사이트 개요.
현대의 정적 사이트 생성기 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이라는 파일에서 생성되며, 이 파일을 생성하고 수정할 수 있습니다.

구성 파일의 특정 job인 pages는 GitLab이 GitLab Pages 웹사이트를 배포하고 있음을 인식하게 합니다.

GitLab Pages 웹사이트에 대한 GitLab 기본 도메인, *.gitlab.io를 사용하거나, 자신의 도메인(example.com)을 사용할 수 있습니다.

이 경우 Pages와 설정을 위해 도메인 등록 기관(또는 제어판)의 관리자여야 합니다.

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

GitLab Pages를 위한 새로운 프로젝트

Pages 사이트에 대한 접근

GitLab Pages의 기본 도메인(.gitlab.io)을 사용하는 경우 웹사이트는 자동으로 안전하며 HTTPS를 통해 제공됩니다.

자신의 사용자 정의 도메인을 사용하는 경우 선택적으로 SSL/TLS 인증서로 보안을 추가할 수 있습니다.

GitLab.com을 사용하는 경우 웹사이트는 인터넷에 공개적으로 제공됩니다.

웹사이트에 대한 접근을 제한하려면 GitLab Pages 접근 제어를 활성화하십시오.

자체 관리 인스턴스를 사용하는 경우 웹사이트는 시스템 관리자가 선택한 Pages 설정에 따라 자신의 서버에 게시됩니다.

Pages 예시

다음 GitLab Pages 웹사이트 예시는 고급 기술을 사용하고 자신의 필요에 맞게 조정하는 데 도움이 될 수 있습니다:

자체 관리 인스턴스를 위한 GitLab Pages 관리

자체 관리 인스턴스에서 GitLab을 실행 중인 경우,

관리 단계를 따르십시오 Pages를 구성합니다.

GitLab Pages 관리 시작 방법에 대한 비디오 튜토리얼을 시청하세요.

Helm 차트(Kubernetes) 인스턴스에서 GitLab Pages 구성하기

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

GitLab Pages의 보안

.이 포함된 네임스페이스

사용자 이름이 example인 경우 GitLab Pages 웹사이트는 example.gitlab.io에 있습니다.
GitLab은 사용자 이름에 .을 포함하는 것을 허용하므로, bar.example라는 이름의 사용자는
실제로는 example.gitlab.io 웹사이트의 서브 도메인인
GitLab Pages 웹사이트 bar.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 고유 도메인 기능을 활성화하세요.

고유 도메인

기본적으로 모든 새로운 프로젝트는 pages 고유 도메인을 사용합니다.
이는 동일한 그룹의 프로젝트가 쿠키를 공유하는 것을 방지하기 위함입니다.

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

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Deploy > Pages를 선택합니다.
  3. Use unique domain 체크박스를 해제합니다.
  4. Save changes를 선택합니다.

예시 URL은 GitLab Pages 기본 도메인 이름을 참조하세요.

만료 배포

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

Pages 배포가 일정 시간이 지난 후 자동으로 삭제되도록 하려면,
pages.expire_in에 기간을 지정하세요:

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

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

만료된 배포는 10분마다 실행되는 cron 작업에 의해 중지됩니다.
중지된 배포는 또한 10분마다 실행되는 또 다른 cron 작업에 의해 삭제됩니다.
이를 복구하려면 중지된 배포 복구에서 설명한 단계를 따르세요.

중지되거나 삭제된 배포는 더 이상 웹에서 사용할 수 없습니다.
사용자는 동일한 URL에서 404 Not found 오류 페이지를 보게 되며,
동일한 URL 구성이 있는 다른 배포가 생성될 때까지 계속됩니다.

중지된 배포 복구

전제 조건:

  • 프로젝트에 대한 Maintainer 역할 이상이 있어야 합니다.

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 배포 > 페이지를 선택합니다.
  3. 배포 근처에서 중지된 배포 포함 토글을 켭니다.
    배포가 아직 삭제되지 않았다면 목록에 포함되어야 합니다.
  4. 복구하려는 배포를 확장하고 복원을 선택합니다.

병렬 배포

세부 사항:
Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
Status: Beta


이 기능의 사용 가능성은 기능 플래그에 의해 제어됩니다.
자세한 내용은 기록을 참조하세요.
이 기능은 테스트 가능하지만 프로덕션 사용 준비가 되어 있지 않습니다.

pages.path_prefix CI/CD 옵션을 사용하여 GitLab Pages URL에 대한 접두사를 구성합니다.
접두사를 사용하면 여러 GitLab Pages 배포를 구분할 수 있습니다:

  • 기본 배포: 빈 path_prefix로 생성된 Pages 배포.
  • 병렬 배포: 비어 있지 않은 path_prefix로 생성된 Pages 배포.

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

  • 소문자로 변환됩니다.
  • 63바이트로 축소됩니다.
  • 숫자(0-9) 및 문자(a-z)를 제외한 모든 문자는 하이픈(-)으로 대체됩니다.
  • 선행 및 후행 하이픈(-)은 제거됩니다.

예제 구성

https://gitlab.example.com/namespace/project와 같은 프로젝트를 고려하십시오.
기본적으로, 그 주 페이지 배포는 다음을 통해 접근할 수 있습니다:

  • 고유 도메인을 사용할 때: https://project-namespace-123456.gitlab.io/.
  • 고유 도메인을 사용하지 않을 때: https://namespace.gitlab.io/project.

프로젝트 브랜치 이름에 대해 pages.path_prefix가 구성된 경우,
예를 들어 path_prefix = $CI_COMMIT_BRANCH, 그리고 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. 배포 > 페이지를 선택합니다.
  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라면, 해당 버전이 기존 경로를 덮어쓰게 됩니다.

즉, https://namespace.gitlab.io/project/documents/index.html는 사이트의 /index.html을 가리키게 되며, documents/index.html은 사이트의 main 배포에서의 파일을 가리키지 않습니다.

CI/CD 변수와 다른 문자열을 혼합하면 경로 충돌 가능성을 줄일 수 있습니다. 예를 들어:

pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}"
  variables:
    PAGES_PREFIX: "" # 기본적으로 접두어 없음 (master)
  pages:
    path_prefix: "$PAGES_PREFIX"
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 기본 브랜치에서 실행 (기본 PAGES_PREFIX와 함께)
    - if: $CI_COMMIT_BRANCH == "staging" # master에서 실행 (기본 PAGES_PREFIX와 함께)
      variables:
        PAGES_PREFIX: '_stg' # 스테이징 브랜치를 위해 _stg로 접두어 추가
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # 병합 요청에 따라 접두어 변경
      when: manual # 병합 요청에서 페이지를 수동으로 실행
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # mr-<iid>로 접두어 추가, 예: `mr-123`

동적 접두어 생성을 위한 문자열과 변수의 혼합 예제입니다:

  • pages.path_prefix: 'mr-$CI_COMMIT_REF_SLUG': 브랜치 또는 태그 이름이 mr-로 접두어가 붙음, 예: mr-branch-name.
  • pages.path_prefix: '_${CI_MERGE_REQUEST_IID}_': 병합 요청 번호가 접두어와 접미어로 _가 붙음, 예: _123_.

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

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

pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}"
  variables:
    PAGES_PREFIX: "" # 기본적으로 접두어 없음 (master)
  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" # master에서 실행되도록 보장 (기본 PAGES_PREFIX와 함께)
      variables:
        PAGES_PREFIX: '_stg' # 스테이징 브랜치를 위해 _stg로 접두어 추가
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # 병합 요청에 따라 접두어 조건부 변경
      when: manual # 병합 요청에서 페이지를 수동으로 실행
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # mr-<iid>로 접두어 추가, 예: `mr-123`

이 구성으로, 사용자는 UI를 통해 각 GitLab Pages 배포에 접근할 수 있습니다.

Pages에 environments를 사용할 때, 모든 페이지 환경이 프로젝트 환경 목록에 나열됩니다.

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

배포 삭제

배포를 삭제하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. Deploy > Pages를 선택하세요.
  3. Deployments 아래에서 삭제하려는 배포의 해당 영역을 선택하세요.
    배포 세부정보가 확장됩니다.
  4. Delete를 선택하세요.

Delete를 선택하면 배포가 즉시 중지됩니다.

중지된 배포는 10분마다 실행되는 크론 작업에 의해 삭제됩니다.

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

자동 정리

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

사용자 정의 작업 이름

  • GitLab 17.5에 customizable_pages_job_name 플래그와 함께 도입됨, 기본적으로 비활성화됨.

역사적으로, 페이지 배포 작업은 페이지 배포를 트리거하기 위해 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라는 이름의 작업의 pages 속성이 false로 설정되면
배포가 트리거되지 않습니다.

pages:
  pages: false