GitLab Pages 가이드

GitLab 페이지 웹 사이트 생성

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

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

해당 GitLab 리포지토리는 SSG(정적 사이트 생성기-Static Site Generators) 또는 일반 HTML에 해당하는 파일을 포함해야 하며, 이 단계를 완료한 후 페이지 사이트가 올바르게 생성되도록 추가 구성을 수행해야 할 수 있다.

1. 왼쪽 사이드바 > Project overview 클릭

2. Set up CI/CD 클릭
   

   

   
   이 버튼이 없는 경우, CI/CD가 프로젝트에 대해 이미 구성되어 있는 것이다. 리포지토리에서 .gitlab-ci.yml 파일을 찾아 수정한다.
   

3. Apply a template 목록에서 사용 중인 SSG에 대한 템플릿을 선택. 평범한 HTML 선택 가능
   

   

   
   사용중인 템플릿을 찾을 수 없으면 GitLab Pages 그룹 샘플 프로젝트를 볼 수 있다. 이러한 프로젝트에는 필요에 따라 수정할 수 있는 .gitlab-ci.yml 파일이 포함되어 있다. 또한 GitLab 페이지용 .gitlab-ci.yml 파일을 직접 작성하는 방법도 배울 수 있다.
   

4. .gitlab-ci.yml 파일을 저장하고 커밋

모든 것이 올바르게 구성되면, 이 사이트를 구축하는 데 약 30분 정도 소요 된다.

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

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

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

1. 상단 내비게이션 바에서 + 버튼 > New project 선택

2. Create from Template 선택

3. Pages 로 시작하는 템플릿 중 하나 선택 > Use template 클릭
   
   

   

4. 양식을 작성한 후 Create project 클릭

5. 왼쪽 사이드바 > CI/CD > Pipelines > Run pipeline 클릭하여 GitLab CI/CD를 트리거하여 사이트를 구축하고 배포

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

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

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

1. GitLab 페이지 예제 그룹으로 이동하여 샘플 프로젝트를 확인

2. 포크를 적용할 프로젝트 이름 클릭

3. 우측 상단 Fork 버튼 클릭하여 포크로 이동할 네임스페이스 선택

4. 왼쪽 사이드바 > CI/CD > Pipelines > Run pipeline 클릭하여 GitLab CI/CD를 트리거하여 사이트를 구축하고 배포

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

리포지토리에 푸시되는 모든 변경에 대해 GitLab CI/CD는 변경사항을 페이지 사이트에 즉시 게시하는 새 파이프라인을 실행한다.

추가 단계 수행:

• 포크 관계 제거

  Settings > General > Advanced settings > Remove fork relationship 클릭

• 네임스페이스와 일치하도록 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)을 찾아 패턴을 반영하도록 설정해야 한다.

예를 들어 Jekyll 의 경우 baseurl은 Jekyll 구성 파일인 _config.yml에 정의되어 있다. 웹 사이트 URL이 https://john.gitlab.io/blog/인 경우, _config.yml 에서 아래와 같이 수정 한다.

baseurl: "/blog"

반대로, 샘플 프로젝트에서 웹사이트를 포크했다면, 모든 예시들이 프로젝트 웹사이트가 있기 때문에 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 오류 페이지를 제공할 수 있다. 일반적으로 이것은 프로젝트의 루트 디렉토리지만, 정적 생성기 구성에 따라 다를 수 있다.

404.html의 경우, 예를 들면 다음과 같다:

• 프로젝트 페이지( /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 클릭

접근 제어가 활성화된 후 누군가가 웹사이트에 접속하려고 시도하면, 그들에게 GitLab에 로그인하여 웹사이트에 접속할 수 있는지 확인할 수 있는 페이지가 제공될 것이다.

페이지 세션 종료

페이지 웹 사이트에서 로그아웃하려면 GitLab 페이지에 대한 응용프로그램 액세스 토큰을 취소한다.

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

그러면 아래의 .gitlab-ci.yml 예는 프로젝트의 루트 디렉터리에서 public 디렉토리로 모든 파일을 이동하기만 하면 된다.

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에서 지정하는 것에만 의존한다. 새 커밋을 특정 페이지에 사용할 브랜치로 아무리 푸시하여도 페이지 작업을 유일한 매개 변수로 제한할 수 있다.

이렇게 하면 프로젝트의 코드는 마스터 브랜치에 저장하고, 정적 사이트 생성기를 호스팅하는 별도 브랜치를 사용할 수 있다(페이지 이름 지정).

다음과 같이 빈 브랜치를 새로 만든다.

git checkout --orphan pages

이 새로운 브랜치에 대한 첫 번째 커밋은 상위 브랜치 없이 다른 모든 브랜치와 완전히 단절된다. 페이지 브랜치에서 정적 생성기의 원본 파일을 푸시한다.

아래는 .gitlab-ci.yml의 복사본이며, 가장 중요한 라인은 마지막 라인으로, 페이지 브랜치에서 모든 것을 실행하도록 지정한다.

image: ruby:2.6

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

압축 자산 제공

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

압축되지 않은 파일을 제공하기 전에 페이지는 .gz 확장자로 동일한 파일이 있는지 여부를 검사한다. 동일한 파일이 있고 브라우저가 압축 파일 수신을 지원한다면, 압축되지 않은 파일 대신 그 버전을 제공할 것이다.

이 기능을 활용하려면 페이지에 업로드하는 아티팩트는 다음과 같은 구조를 가져야 한다.

public/
├─┬ index.html
│ └ index.html.gz
│
├── css/
│   └─┬ main.css
│     └ main.css.gz
│
└── js/
    └─┬ main.js
      └ main.js.gz

.gitlab-ci.yml 파일의 페이지 작업에 다음과 같은 script: 명령을 포함하면 이를 달성할 수 있다.

pages:
  # Other directives
  script:
    # Build the public/ directory first
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \;

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

모호한 URL 해결

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

다음 파일과 함께 배포된 페이지 사이트의 경우 :

public/
├─┬ index.html
│ ├ data.html
│ └ info.html
│
├── data/
│   └── index.html
├── info/
│   └── details.html
└── other/
    └── index.html

페이지는 여러 개의 다른 URL을 통해 이러한 파일 각각에 도달하는 것을 지원한다. 특히 URL이 디렉토리만 지정하는 경우 항상 index.html 파일을 찾는다. URL이 존재하지 않는 파일을 참조하지만 URL에 .html을 추가하면 존재하는 파일이 제공된다. 위 페이지 사이트에 대하여 아래 몇 가지 예를 확인하여 보면 :