Page Comparison

GitLab 페이지 웹 사이트 생성

CI/CD 템플릿을 사용하여 페이지 웹 사이트 생성

페이지 사이트를 추가할 기존 프로젝트가 있는 경우 .gitlab-ci.yml 템플릿 사용

...

CI / CD > Pipelines 에서 파이프라인이 돌아가는 것을 볼 수 있으며, 파이프라인이 완료되면 Settings > Pages로 이동하여 페이지 웹 사이트에 대한 링크를 찾을 수 있다.

새 프로젝트 템플릿에서 페이지 웹 사이트 생성

GitLab Pages를 테스트하거나 이미 Pages 사이트를 생성하도록 구성된 새 프로젝트를 시작하려는 경우 프로젝트 템플릿을 사용

...

이 사이트를 구축하는 데 약 30분이 걸릴 수 있다. 파이프라인이 완료되면, Settings > Pages로 이동하여 페이지 웹 사이트에 대한 링크를 찾을 수 있다.

포크한 샘플에서 페이지 웹 사이트 생성

GitLab은 가장 인기 있는 정적 사이트 생성기를 위한 샘플 프로젝트를 제공한다. 샘플 프로젝트 중 하나를 포크하고 CI/CD 파이프라인을 실행하여 페이지 웹 사이트를 생성할 수 있다.

...

• 네임스페이스와 일치하도록 URL 변경
  Settings > General > Advanced settings > Change path > <namespace>.gitlab.io로 변경
  SSG의 구성 파일로 이동하여 기본 URL을 "프로젝트 이름"에서 ""로 변경. 프로젝트 이름 설정은 SSG에 따라 다르며 구성 파일에 없을 수 있다.
  

  

GitLab 페이지 웹 사이트 업데이트

GitLab 페이지 도메인 이름, URL 및 baseurl

GitLab 페이지 기본 도메인 이름

GitLab.com에 페이지 프로젝트를 설정하면 namespace.example.io의 하위 도메인에서 자동으로 접속할 수 있다. 네임스페이스는 GitLab.com의 사용자 이름 또는 이 프로젝트를 만든 그룹 이름으로 정의된다. GitLab 자체 관리 인스턴스의 경우 example.io을 인스턴스의 페이지 도메인으로 변경해야 한다. GitLab.com의 경우 페이지 도메인은 *.gitlab.io이다.

...

프로젝트 웹 사이트 예제

• 사용자 john이 blog라는 프로젝트를 만들었을 경우 - URL : https://gitlab.com/john/blog/
  이 프로젝트에 GitLab Pages를 사용 가능으로 설정 시 https://john.gitlab.io/blog/ 에서 이 페이지를 사용할 수 있다.

• websites라고 하는 모든 웹 사이트에 대한 그룹을 만들었고, 이 그룹 내의 프로젝트를 blog라고 부른다 - URL : https://gitlab.com/websites/blog/
  이 프로젝트에 GitLab Pages를 사용 가능으로 설정 시 https://websites.gitlab.io/blog/ 에서 이 페이지를 사용할 수 있다.

• 엔지니어링 부서에 대한 engineering 그룹을 만들고 docs라는 모든 문서 웹 사이트에 대한 하위 그룹을 만들었으며, 이 하위 그룹 내의 프로젝트를 workflows라고 부른다 - URL : https://gitlab.com/engineering/docs/workflows/
  이 프로젝트에 GitLab Pages를 사용 가능으로 설정 시 https://engineering.gitlab.io/docs/workflows 에서 이 페이지를 사용할 수 있다.

사용자 및 그룹 웹 사이트 예제

• 사용자 John 이 john.gitlab.io라는 프로젝트를 만들었다 - URL : https://gitlab.com/john/john.gitlab.io
  프로젝트에 GitLab Pages를 사용 가능으로 설정하면 웹 사이트가 https://john.gitlab.io에 게시된다.

• websites그룹에 websites.gitlab.io라는 프로젝트를 만들었다 - URL : https://gitlab.com/websites/websites.gitlab.io
  프로젝트에 GitLab Pages를 사용 가능으로 설정하면 웹 사이트가 https://websites.gitlab.io에 게시된다.

URL 및 baseurls

모든 정적 사이트 생성기(SSG) 기본 구성은 해당 도메인의 하위 디렉토리(example.com/subdir)가 아닌 하위 도메인(example.com)에서 웹 사이트를 찾을 것으로 예상한다. 따라서 프로젝트 웹 사이트(namespace.gitlab.io/project-name)를 게시할 때, SSG 문서에서 이 구성(기본 URL)을 찾아 패턴을 반영하도록 설정해야 한다.

...

반대로, 샘플 프로젝트에서 웹사이트를 포크했다면, 모든 예시들이 프로젝트 웹사이트가 있기 때문에 baseurl은 이미 위와 같이 구성되었을 것이다. 사용자 또는 그룹 웹 사이트를 만들려면 프로젝트에서 이 구성을 제거하여야 한다. 예을 들어 Jekyll 의 경우 _config.yml을 다음과 같이 변경해야 한다.

baseurl: ""

GitLab 페이지 탐색

GitLab 페이지 요구 사항

GitLab 페이지에 웹 사이트를 업로드하는 데 필요한 내용은 다음과 같다.

1. 인스턴스의 도메인 : GitLab 페이지에 사용되는 도메인 이름(관리자에게 문의)

2. GitLab CI/CD: 리포지토리의 루트 디렉터리에 pages라는 특정 작업이 있는 .gitlab-ci.yml 파일

3. 사이트의 repo에서 게시할 내용을 포함하는 public이라고 이름지어진 디렉토리

4. 프로젝트에 사용할 수 있는 GitLab 러너

GitLab.com의 GitLab 페이지

GitLab.com에서 GitLab 페이지를 사용하여 웹 사이트를 호스트하는 경우:

• GitLab.com의 GitLab 페이지의 도메인 이름은 gitlab.io이다.

• 사용자 지정 도메인 및 TLS 지원이 가능하다.

• 공유 러너는 기본적으로 사용 가능하고 무료로 제공되며 웹사이트 구축에 사용할 수 있다. 개별 러너를 등록하여 사용도 가능하다.

사용자 정의 오류 코드 페이지

아티팩트에 포함될 public디렉토리의 루트에 각각 403.html과 404.html 파일을 생성하여 자신만의 403 및 404 오류 페이지를 제공할 수 있다. 일반적으로 이것은 프로젝트의 루트 디렉토리지만, 정적 생성기 구성에 따라 다를 수 있다.

...

• 프로젝트 페이지( /projectname/에서 제공됨)를 사용하고 /projectname/non/existing_file에 접속하려고 하면 GitLab 페이지가 먼저 /projectname/404.html, 그 다음 /404.html을 제공하려고 시도한다.

• 사용자/그룹 페이지( /에서 제공됨)를 사용하고 /non/existing_file에 접속하려고 하면 GitLab 페이지가 /404.html를 제공하려고 시도한다.

• 사용자 지정 도메인을 사용하고 /non/existing_file에 접속하려고 하면 GitLab 페이지는 /404.html만 제공하려고 시도한다.

GitLab 페이지에서 리디렉션

사용자 정의 서버 구성 파일(예: .htaccess 또는 .conf 파일)은 사용할 수 없으므로 페이지를 다른 위치로 리디렉션하려면 HTTP 메타데이터 새로 고침 태그를 사용하여야 한다.

일부 정적 사이트 생성기는 HTML 파일을 수동으로 만들고 편집할 필요가 없도록 해당 기능을 위한 플러그인을 제공한다. 예를 들어, Jekyll은 리디렉션-From 플러그인을 가지고 있다.

GitLab 페이지 액세스 제어

프로젝트 구성원(최소 게스트까지)만 웹 사이트에 액세스할 수 있도록 프로젝트에서 페이지 액세스 제어를 설정할 수 있다.

...

1. 프로젝트의 Settings > General > Visibility, project features, permissions 확장

2. Pages 버튼 전환
   토글 버튼이 표시되지 않으면 활성화되지 않은 상태. 관리자에게 활성화 요청

3. 페이지 접근 제어 드롭다운을 사용하면 프로젝트의 가시성에 따라 GitLab 페이지로 호스팅되는 페이지를 볼 수 있는 사용자를 설정할 수 있다.

   • 프로젝트가 private인 경우 :
     Only project members : 프로젝트 구성원만 웹사이트를 탐색 가능
     Everyone : GitLab에 접속 가능한(로그인/로그아웃 상관없이) 모든사용자는 프로젝트 권한에 상관없이 웹사이트를 탐색 가능

   • 프로젝트가 internal인 경우 :
     Only project members : 프로젝트 구성원만 웹사이트를 탐색 가능
     Everyone with access : GitLab에 로그인한 모든사용자는 프로젝트 권한에 상관없이 웹사이트를 탐색 가능
     Everyone : GitLab에 접속 가능한(로그인/로그아웃 상관없이) 모든사용자는 프로젝트 권한에 상관없이 웹사이트를 탐색 가능

   • 프로젝트가 public인 경우 :
     Only project members : 프로젝트 구성원만 웹사이트를 탐색 가능
     Everyone with access : GitLab에 접속 가능한(로그인/로그아웃 상관없이) 모든사용자는 프로젝트 권한에 상관없이 웹사이트를 탐색 가능

4. Save changes 클릭

...

1. 프로필의 Settings > Application으로 이동

2. 페이지 하단에서 Authorized applications 검색

3. GitLab 페이지 > Revoke 버튼 클릭

페이지 게시 취소

페이지 내용을 정리해야 할 경우 :

1. 프로젝트 Settings > Pages로 이동

2. Remove pages 버튼 클릭

...

제한 사항

GitLab 인스턴스의 일반 도메인(*.example.io)에서 페이지를 사용할 경우 하위 하위 도메인에서는 HTTPS를 사용할 수 없다. 즉, 사용자 이름/그룹 이름에 점(예: foo.bar)이 포함되어 있으면 도메인 https://foo.bar.example.io은 동작하지 않는다. 이것은 HTTP Over TLS 프로토콜의 제한이다. HTTP를 HTTPS로 리디렉션하지 않으면 HTTP 페이지는 계속 동작한다.

GitLab 페이지는 하위 그룹에 대한 그룹 웹 사이트를 지원하지 않는다. 최상위 그룹 웹 사이트만 만들 수 있다.

페이지에 대한 특정 구성 옵션

특정 사용 사례에 맞게 GitLab CI/CD를 설정하는 방법

일반 HTML 웹 사이트용 .gitlab-ci.yml

리포지토리에 다음 파일이 포함된 것으로 가정

├── index.html
├── css
│   └── main.css
└── js
    └── main.js

...

pages:
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master

정적 사이트 생성기(SSG)용 .gitlab-ci.yml

단계별 가이드 문서 참조

실제 코드가 있는 저장소의 .gitlab-ci.yml

GitLab 페이지는 기본적으로 분기/태그에 구애받지 않으며 배포는 .gitlab-ci.yml에서 지정하는 것에만 의존한다. 새 커밋을 특정 페이지에 사용할 브랜치로 아무리 푸시하여도 페이지 작업을 유일한 매개 변수로 제한할 수 있다.

...

image: ruby:2.6

pages:
  script:
  - gem install jekyll
  - jekyll build -d public/
  artifacts:
    paths:
    - public
  only:
  - pages

압축 자산 제공

대부분의 최신 브라우저는 압축된 형식의 파일 다운로드를 지원한다. 이것은 파일 크기를 줄임으로써 다운로드 속도를 높인다.

...

파일을 미리 압축하고 아티팩트에 두 버전을 모두 포함함으로써 페이지는 주문형 파일을 압축할 필요 없이 압축 및 압축되지 않은 콘텐츠에 대한 요청을 처리할 수 있다.

모호한 URL 해결

GitLab Pages는 확장자를 포함하지 않는 URL에 대한 요청을 수신할 때 어떤 파일을 서비스할 것인지에 대한 가정을 한다.

...

사용자 지정 도메인 및 SSL/TLS 인증서

GitLab 페이지의 선택적 기능으로, 사용자 지정 도메인으로 GitLab 페이지를 설정하고 여기에 SSL/TLS 인증서를 추가한다.

사용자 지정 도메인으로 페이지 설정

요구사항

• GitLab 페이지 웹 사이트 가동 및 실행, 기본 페이지 도메인(*.gitlab.io, GitLab.com)

• 사용자 지정 도메인 이름 example.com 또는 하위 도메인 subdomain.example.com

• 도메인의 서버 제어판에 액세스하여 DNS 레코드 설정:

  • 도메인이 GitLab 페이지 서버를 가리키는 DNS A 또는 CNAME 레코드

  • 도메인의 소유권을 확인하기 위한 DNS TXT 레코드

Step

사용자 정의 도메인을 페이지에 추가하려면 아래 단계를 따른다. DNS 레코드에 대한 개요는 이 페이지를 참조한다.

1. 페이지에 사용자 지정 도메인 추가

프로젝트의 Setting > Pages > + New domain 클릭하여 사용자 지정 도메인을 GitLab 페이지에 추가. 다음 중 하나를 선택.
- SSL/TLS 인증서 추가
- 공백으로 남겨놓는다.(나중에 추가할 수 있음)

...

Create New Domain 클릭

2. 확인 코드 받기

일단 페이지에 새 도메인을 추가하면, 확인 코드가 프롬프트된다. 해당 값을 복사하여 다음 단계에서 도메인의 제어판에 TXT 레코드로 붙여 넣으면 된다.

...

3. 페이지에 대한 DNS 레코드 설정

루트 도메인의 경우

루트 도메인(example.com)의 요구 사항:

...

서브 도메인의 경우

서브 도메인(subdomain.example.com)의 요구 사항:

...

사용자든 프로젝트 웹 사이트든 CNAME은 프로젝트 디렉토리가 아닌 페이지 도메인(namespace.gitlab.io)을 가리켜야 한다는 점에 유의.

...

루트 및 하위 도메인의 경우

예를 들어, example.com과 www.example.com과 같이 하위 도메인과 루트 도메인이 모두 동일한 웹 사이트를 가리켜야 하는 경우, 요구 사항은 다음과 같다:

...

4. 도메인의 소유권 확인

모든 DNS 레코드를 추가한 후:

1. 프로젝트의 Settings > Pages

2. 도메인 이름을 찾고 Details 클릭

3. 새 도메인을 활성화하려면 Retry verification 클릭

...

페이지 도메인 검증 문제 해결

도메인 검증 TXT DNS 항목을 올바르게 구성했는지 수동으로 확인하려면 터미널에서 다음 명령을 실행:

...

;; ANSWER SECTION:
_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>"

도메인 별칭 추가

동일한 프로젝트에 둘 이상의 별칭(사용자 지정 도메인 및 하위 도메인)을 추가할 수 있다. 별칭은 하나의 방으로 통하는 문을 많이 만들 수 있는 것으로 이해할 수 있다.

사이트에 설정한 모든 가명들은 Setting > Pages에 나열된다. 이 페이지에서 해당 페이지를 보고, 추가하고, 제거할 수 있다.

Cloudflare를 사용하여 www.domain.com으로 리디렉션

Cloudflare를 사용할 경우 GitLab에 www.domain.com과 domain.com을 모두 추가하지 않고도 www를 domain.com으로 리디렉션할 수 있다.

1. Cloudflare에서 domain.com을 35.185.44.232로 가리키는 DNS A 레코드 생성

2. GitLab에서 GitLab 페이지에 도메인을 추가하고 확인 코드 획득

3. Cloudflare에서 DNS TXT 레코드를 생성하여 도메인 확인

4. GitLab에서 도메인 확인

5. Cloudflare에서 wwww domain.com을 가리키는 DNS CNAME 레코드를 생성

6. Cloudflare에서 www.domain.com을 가리키는 페이지 규칙을 domain.com에 추가
   - 도메인의 대시보드 > 상단 탐색기에서 Page Rules 클릭
   - Create Page Rule 클릭
   - 도메인 www.domain.com을 입력하고 + Add a Setting 클릭
   - 드롭다운 메뉴에서 Forwarding URL 선택 > 상태 코드 301 - Permanent Redirect 선택
   - 대상 URL https://domain.com 입력

페이지에 SSL/TLS 인증서 추가

SSL/TLS 인증에 대한 개요는 이 페이지를 참조한다.

...

• 페이지 도메인에 대한 SSL 인증서를 자동으로 가져오고 갱신하는 GitLab 페이지와의 암호화 통합 사용

• 아래 단계에 따라 수동으로 GitLab 페이지 웹 사이트에 SSL/TLS 인증서 추가

요구사항

• 사용자 지정 도메인을 통해 가동 및 실행 액세스 할 수 있는 GitLab 페이지 웹 사이트

• PEM 인증서 : CA에서 생성한 인증서로서 Certificate (PEM) 필드에 추가 필요

• 중간 인증서 : ("root certificate"라고 함), CA를 식별하는 암호화 키체인의 부분이다. 보통 PEM 인증서와 결합되지만 수동으로 추가해야 하는 경우도 있다. CloudFlare 인증서는 이러한 사례 중 하나이다.

• 개인 키 : 도메인에 대해 PEM을 검증하는 암호화된 키

Steps

• 새 도메인을 추가할 때 인증서를 추가하려면 Settings > Pages > New Domain으로 이동하여 도메인 이름과 인증서를 추가

• 이전에 추가된 도메인에 인증서를 추가하려면 프로젝트의 Settings > Pages로 이동하여 도메인 이름을 찾고 Details 및 Edit을 클릭하여 인증서를 추가

...

GitLab 페이지 웹 사이트에 HTTPS 강제 적용

웹 사이트 방문자의 보안을 강화하기 위해 GitLab 페이지에 HTTPS를 적용하도록 선택할 수 있다. 이렇게 하면 HTTP를 통해 웹 사이트를 방문하려는 모든 시도가 301을 통해 HTTPS로 자동 리디렉션된다.

...

GitLab 페이지와 Let's Encryption과의 통합

GitLab Pages와 LE(Let's Encrypt)를 통합하면 사용자가 인증서를 직접 발급하고 업데이트해야 하는 번거로움 없이 사용자 지정 도메인이 있는 페이지 웹 사이트에 대한 LE 인증서를 사용할 수 있으며, GitLab은 곧바로 사용이 가능하다.

...

요구사항

도메인에 대한 SSL 인증서의 자동 공급을 실행하기 전에 다음이 있는지 확인:

...

사용자 지정 도메인에 대해 암호화 사용

요구 사항을 충족한 후 Let's Encryption 통합:

...

문제 해결

“Something went wrong while obtaining the Let’s Encrypt certificate” 오류

Let's Encryption 인증서를 가져오는 동안 오류가 발생한 경우, 다음 단계를 수행하여 인증서를 다시 획득한다.

1. 프로젝트의 Settings > Pages로 이동

2. 도메인에서 Edit 클릭

3. Retry 클릭

4. 여전히 동일한 오류가 발생하는 경우:

   1. 도메인에 대한 CNAME 또는 DNS 레코드를 하나만 올바르게 설정했는지 확인

   2. 도메인에 AAAA DNS 레코드가 없는지 확인

   3. 도메인 또는 상위 도메인에 대한 CAA DNS 레코드가 있는 경우 letsencrypt.org이 포함되어 있는지 확인

   4. 도메인이 검증되었는지 확인

   5. 1단계로 이동

“GitLab is obtaining a Let’s Encrypt SSL certificate for this domain. This process can take some time. Please try again later.” 메시지 표시 후 한 시간 이상 대기중일 경우

다음 단계에 따라 GitLab 페이지에 대한 도메인을 제거하고 다시 추가한다.

1. 프로젝트의 Settings > Pages로 이동

2. 도메인에서 Remove 클릭

3. 도메인을 다시 추가하고 확인

4. 도메인에 대한 통합 암호화 사용

5. 시간이 흐른 후에도 동일한 메시지가 표시되는 경우:

   1. 도메인에 대한 CNAME 또는 DNS 레코드를 하나만 올바르게 설정했는지 확인

   2. 도메인에 AAAA DNS 레코드가 없는지 확인

   3. 도메인 또는 상위 도메인에 대한 CAA DNS 레코드가 있는 경우 letsencrypt.org이 포함되어 있는지 확인

   4. 1단계로 이동

기술 문서 및 참조 페이지

...