GitLab Pages는 GitLab의 리포지터리에서 바로 정적 웹사이트를 게시합니다.

이러한 웹사이트의 특징은 다음과 같습니다:

• GitLab CI/CD 파이프라인으로 자동 배포됩니다.
• Hugo, Jekyll, Gatsby 같은 모든 정적 사이트 생성기와 순수 HTML, CSS, JavaScript, Wasm을 지원합니다.
• 추가 비용 없이 GitLab 이 제공하는 인프라에서 실행됩니다.
• 사용자 정의 도메인 및 SSL/TLS 인증서와 연결됩니다.
• 내장 인증으로 접근을 제어합니다.
• 개인, 비즈니스, 프로젝트 문서 사이트 규모에 맞춰 안정적으로 확장됩니다.

Pages로 웹사이트를 게시할 때는 Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, Brunch 같은 정적 사이트 생성기를 사용합니다. Pages는 순수 HTML, CSS, JavaScript, Wasm으로 직접 작성한 웹사이트도 지원합니다. .php 나 .asp 같은 동적 서버 사이드 처리는 지원하지 않습니다. 자세한 내용은 정적 vs 동적 웹사이트를 참고합니다.

시작하기#

GitLab Pages 웹사이트를 만드는 방법은 다음과 같습니다:

GitLab Pages 웹사이트를 업데이트하는 방법은 다음과 같습니다:

자세한 내용은 다음을 참고합니다:

GitLab Pages 사용#

GitLab Pages를 사용하려면 웹사이트 파일을 업로드할 프로젝트를 GitLab에 만들어야 합니다. 이 프로젝트는 공개, 내부, 비공개 중 어느 것이든 가능합니다.

기본적으로 GitLab은 리포지터리의 public이라는 특정 폴더에서 웹사이트를 배포합니다. Pages로 배포할 폴더를 직접 지정할 수도 있습니다. GitLab에서 새 프로젝트를 만들면 리포지터리가 자동으로 생성됩니다.

사이트를 배포할 때 GitLab은 내장 도구인 GitLab CI/CD로 사이트를 빌드하고 GitLab Pages 서버에 게시합니다. 이 작업을 위해 GitLab CI/CD가 실행하는 스크립트 순서는 .gitlab-ci.yml이라는 파일에 정의되며, 이 파일은 직접 만들고 수정할 수 있습니다. 구성 파일에 pages: true 속성을 가진 사용자 정의 job 이 있으면 GitLab은 GitLab Pages 웹사이트를 배포한다고 인식합니다.

GitLab의 GitLab Pages 웹사이트 기본 도메인인 *.gitlab.io를 사용하거나, 직접 보유한 도메인(example.com)을 사용할 수 있습니다. 후자의 경우 Pages를 설정하려면 도메인 등록 기관(또는 제어판)의 관리자여야 합니다.

Pages 사이트 접근#

GitLab Pages 기본 도메인(.gitlab.io)을 사용하면 웹사이트는 자동으로 보안이 적용되어 HTTPS로 제공됩니다. 직접 보유한 사용자 정의 도메인을 사용하는 경우에는 SSL/TLS 인증서로 보안을 적용할 수 있습니다.

GitLab.com을 사용하면 웹사이트가 인터넷에 공개됩니다. 웹사이트 접근을 제한하려면 GitLab Pages 접근 제어를 켭니다.

GitLab Self-Managed 인스턴스를 사용하면 웹사이트는 시스템 관리자가 선택한 Pages 설정에 따라 자체 서버에 게시되며, 관리자는 사이트를 공개 또는 내부로 지정할 수 있습니다.

Pages 예시#

다음 GitLab Pages 웹사이트 예시에서 필요에 맞게 활용할 수 있는 고급 기법을 확인할 수 있습니다:

• iOS에서 GitLab Pages 블로그에 글 올리기.
• GitLab CI: job을 순차 또는 병렬로 실행하거나 사용자 정의 파이프라인 구축하기.
• GitLab CI: 배포와 환경.
• Nanoc, GitLab CI, GitLab Pages로 새 GitLab 문서 사이트 구축하기.
• GitLab Pages로 코드 커버리지 리포트 게시하기.

GitLab Self-Managed 인스턴스에 대한 GitLab Pages 관리#

GitLab Self-Managed 인스턴스를 운영하는 경우 관리 절차에 따라 Pages를 구성합니다.

GitLab Pages 관리를 시작하는 방법은 동영상 튜토리얼에서 확인할 수 있습니다.

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

Helm 차트(Kubernetes)로 배포한 인스턴스에서 GitLab Pages를 구성하려면 다음 중 하나를 사용합니다:

• gitlab-pages 서브차트.
• 외부 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을 아예 지정하지 않는 것입니다:

// Safe: This cookie is only visible to example.gitlab.io
document.cookie = "key=value";

// Unsafe: This cookie is visible to example.gitlab.io and its subdomains,
// regardless of the presence of the leading dot.
document.cookie = "key=value;domain=.example.gitlab.io";
document.cookie = "key=value;domain=example.gitlab.io";

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

공유 쿠키#

기본적으로 한 그룹의 모든 프로젝트는 group.gitlab.io처럼 동일한 도메인을 공유합니다. 즉 그룹 내 모든 프로젝트가 쿠키도 함께 공유합니다.

프로젝트마다 다른 쿠키를 사용하게 하려면 프로젝트에 Pages 고유 도메인 기능을 켭니다.

고유 도메인#

히스토리

• GitLab 17.4에서 고유 도메인 URL 이 더 짧아지도록 변경되었습니다.

기본적으로 모든 새 프로젝트는 같은 그룹의 프로젝트끼리 쿠키를 공유하지 않도록 Pages 고유 도메인을 사용합니다.

프로젝트 메인테이너는 이 기능을 다음과 같이 끌 수 있습니다:

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

URL 예시는 GitLab Pages 기본 도메인 이름을 참고합니다.

기본 도메인#

히스토리

• GitLab 17.8에서 도입되었습니다.

사용자 정의 도메인과 함께 GitLab Pages를 사용할 때는 GitLab Pages로 오는 모든 요청을 기본 도메인으로 리디렉션할 수 있습니다. 기본 도메인을 선택하면 사용자는 308 Permanent Redirect 상태를 받고 브라우저가 선택한 기본 도메인으로 리디렉션됩니다. 브라우저가 이 리디렉션을 캐시할 수 있습니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.
• 사용자 정의 도메인이 설정되어 있어야 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. Primary domain 드롭다운 목록에서 리디렉션할 도메인을 선택합니다.
4. Save changes를 선택합니다.

만료 배포#

히스토리

• GitLab 17.4에서 도입되었습니다.
• 변수 지원이 GitLab 17.11에서 도입되었습니다.

pages.expire_in에 기간을 지정하면 일정 시간이 지난 뒤 Pages 배포가 자동으로 삭제되도록 구성할 수 있습니다:

create-pages:
  stage: deploy
  script:
    - ...
  pages:  # specifies that this is a Pages job and publishes the default public directory
    expire_in: 1 week

만료된 배포는 10분마다 실행되는 cron job 이 중지합니다. 중지된 배포는 역시 10분마다 실행되는 다른 cron job 이 삭제합니다. 배포를 복구하려면 중지된 배포 복구에 설명된 단계를 따릅니다.

중지되거나 삭제된 배포는 더 이상 웹에서 제공되지 않습니다. 동일한 URL 구성으로 새 배포가 만들어질 때까지 해당 URL에서는 404 Not found 오류 페이지가 표시됩니다.

앞의 YAML 예시는 사용자 정의 job 이름을 사용합니다.

중지된 배포 복구#

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

아직 삭제되지 않은 중지된 배포를 복구하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. Deployments 옆의 Include stopped deployments 토글을 켭니다. 배포가 아직 삭제되지 않았다면 목록에 표시됩니다.
4. 복구할 배포를 확장하고 Restore를 선택합니다.

배포 삭제#

배포를 삭제하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Pages를 선택합니다.
3. Deployments에서 삭제할 배포의 아무 영역이나 선택합니다. 배포 상세 정보가 펼쳐집니다.
4. Delete를 선택합니다.

Delete를 선택하면 배포가 즉시 중지됩니다. 중지된 배포는 10분마다 실행되는 cron job 이 삭제합니다.

아직 삭제되지 않은 중지된 배포를 복원하려면 중지된 배포 복구를 참고합니다.

사용자 정의 job 이름#

히스토리

• GitLab 17.5에서 기본적으로 비활성화된 customizable_pages_job_name 플래그와 함께 도입되었습니다.
• GitLab 17.6에서 일반 공개되었습니다. 기능 플래그 customizable_pages_job_name은 제거되었습니다.

어떤 job 에서든 Pages 배포를 트리거하려면 job 정의에 pages 속성을 포함합니다. 이 속성은 true로 설정한 불리언이거나 해시일 수 있습니다.

예를 들어 true를 사용하는 경우는 다음과 같습니다:

deploy-my-pages-site:
  stage: deploy
  script:
    - npm run build
  pages: true  # specifies that this is a Pages job and publishes the default public directory

예를 들어 해시를 사용하는 경우는 다음과 같습니다:

deploy-pages-review-app:
  stage: deploy
  script:
    - npm run build
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: '_staging'

pages라는 이름의 job에서 pages 속성을 false로 설정하면 배포가 트리거되지 않습니다:

pages:
  pages: false

병렬 배포#

예를 들어 리뷰 앱을 만들 때처럼 프로젝트에 여러 배포를 동시에 만들려면 병렬 배포 문서를 참고합니다.