튜토리얼: 처음부터 GitLab Pages 웹사이트 만들기
GitLab v19.5Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
이 튜토리얼에서는 정적 사이트 생성기(SSG)인 Jekyll로 Pages 사이트를 처음부터 만드는 방법을 설명합니다. 이 예시는 Jekyll을 사용하지만 다른 SSG도 비슷한 단계를 따릅니다. 순수 HTML로 Pages 사이트를 만들려면 CI/CD 템플릿으로 GitLab Pages 웹사이트 만들기 튜토리얼을 참고합니다.
이 튜토리얼에서는 정적 사이트 생성기(SSG)인 Jekyll로 Pages 사이트를 처음부터 만드는 방법을 설명합니다. 빈 프로젝트에서 시작해 러너에 지시를 내리는 CI/CD 설정 파일을 직접 만듭니다. CI/CD 파이프라인이 실행되면 Pages 사이트가 생성됩니다.
이 예시는 Jekyll을 사용하지만 다른 SSG도 비슷한 단계를 따릅니다. 이 튜토리얼을 진행하는 데 Jekyll 이나 SSG에 익숙할 필요는 없습니다.
순수 HTML로 Pages 사이트를 만들려면 CI/CD 템플릿으로 GitLab Pages 웹사이트 만들기 튜토리얼을 참고합니다. 사용할 수 있는 템플릿 목록은 프로젝트 템플릿에서 확인합니다.
GitLab Pages 웹사이트를 만드는 순서는 다음과 같습니다.
- 1단계: 프로젝트 파일 생성
- 2단계: Docker 이미지 선택
- 3단계: Jekyll 설치
- 4단계: 출력용
public디렉터리 지정 - 5단계: 아티팩트용
public디렉터리 지정 - 6단계: 웹사이트 배포 및 확인
시작하기 전에#
GitLab에 빈 프로젝트가 있어야 합니다.
프로젝트 파일 생성#
루트(최상위) 디렉터리에 파일 3개를 만듭니다.
-
.gitlab-ci.yml: 실행할 명령을 담는 YAML 파일입니다. 지금은 파일 내용을 비워 둡니다. -
index.html: 원하는 HTML 콘텐츠를 채워 넣을 수 있는 비어 있지 않은 HTML 파일입니다. 예를 들면 다음과 같습니다.<html> <head> <title>Home</title> </head> <body> <h1>Hello World!</h1> </body> </html> -
Gemfile: Ruby 프로그램의 의존성을 기술하는 파일입니다.다음 내용을 채워 넣습니다.
source "https://rubygems.org" gem "jekyll"
Docker 이미지 선택#
이 예시에서 러너는 Docker 이미지로 스크립트를 실행하고 사이트를 배포합니다.
여기서 사용하는 Ruby 이미지는 DockerHub에서 관리됩니다.
.gitlab-ci.yml 파일 맨 앞에 다음 CI/CD 설정을 추가해 파이프라인의 기본 이미지를 지정합니다.
default:
image: ruby:3.2
빌드에 NodeJS가 필요한 SSG 라면 파일 시스템에 NodeJS가 포함된
이미지를 지정해야 합니다. 예를 들어 Hexo 사이트에서는
image: node:12.17.0을 사용할 수 있습니다.
Jekyll 설치#
Jekyll을 로컬에서 실행하려면 먼저 설치해야 합니다.
- 터미널을 엽니다.
gem install bundler를 실행해 Bundler를 설치합니다.bundle install을 실행해Gemfile.lock을 만듭니다.bundle exec jekyll build를 실행해 Jekyll을 설치합니다.
프로젝트에서 Jekyll을 실행하려면 .gitlab-ci.yml 파일을 편집해
설치 명령을 추가합니다.
script:
- gem install bundler
- bundle install
- bundle exec jekyll build
또한 .gitlab-ci.yml 파일에서 각 script는 job 단위로 구성됩니다.
job에는 해당 작업에 적용할 스크립트와 설정이
들어갑니다.
job:
script:
- gem install bundler
- bundle install
- bundle exec jekyll build
GitLab Pages에서는 이 job에 pages 속성이 있어야 합니다.
이 설정은 해당 job으로 GitLab Pages에 웹사이트를 배포하겠다는 뜻을
러너에 알립니다.
create-pages:
script:
- gem install bundler
- bundle install
- bundle exec jekyll build
pages: true # specifies that this is a Pages job
이 페이지의 예시는 사용자 정의 job 이름을 사용합니다.
출력용 public 디렉터리 지정#
Jekyll에 출력물을 어디에 생성할지 알려 주어야 합니다.
GitLab Pages는 public이라는 디렉터리의 파일만 사용합니다.
Jekyll은 빌드된 웹사이트의 출력 디렉터리를 지정하는 데 대상 플래그(-d)를 사용합니다.
.gitlab-ci.yml 파일에 대상 디렉터리를 추가합니다.
create-pages:
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job
아티팩트용 public 디렉터리 지정#
히스토리
pages.publish경로를artifacts:paths에 자동으로 추가하는 동작은 GitLab 17.10에서 Pages job 에만 도입.
Jekyll 이 public 디렉터리에 파일을 출력했으므로, 이제 러너가 그 파일을 어디서 가져올지
알아야 합니다. GitLab 17.10 이상에서는 Pages job에 한해
pages.publish 경로를 명시하지 않으면
public 디렉터리가 artifacts:paths에
자동으로 추가됩니다.
create-pages:
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
이제 .gitlab-ci.yml 파일은 다음과 같습니다.
default:
image: ruby:3.2
create-pages:
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
웹사이트 배포 및 확인#
앞의 단계를 모두 마쳤다면 웹사이트를 배포합니다.
.gitlab-ci.yml파일을 저장하고 커밋합니다.- Build > Pipelines로 이동해 파이프라인을 확인합니다.
- 파이프라인이 끝나면 Deploy > Pages로 이동해 Pages 웹사이트 링크를 확인합니다.
이 pages job 이 성공하면 파이프라인 화면에 pages:deploy라는 특수 job 이
표시됩니다. 이 job은 GitLab Pages 데몬이 쓸 수 있도록 웹사이트 콘텐츠를 준비합니다.
GitLab 이 백그라운드에서 실행하며 러너를 사용하지 않습니다.
CI/CD 파일의 그 밖의 옵션#
더 복잡한 작업을 하려면 다른 CI/CD YAML 키워드로
.gitlab-ci.yml 파일을 수정할 수 있습니다. .gitlab-ci.yml 파일은 GitLab에 포함된
CI Lint 도구로 검증할 수 있습니다.
다음 절에서는 CI/CD 파일에 추가할 수 있는 다른 옵션을 설명합니다.
특정 브랜치만 Pages 사이트에 배포#
특정 브랜치에서만 Pages 사이트에 배포하고 싶을 수 있습니다.
먼저 브랜치에 변경 사항이 푸시될 때만 파이프라인이 실행되도록 workflow 절을
추가합니다.
default:
image: ruby:3.2
workflow:
rules:
- if: $CI_COMMIT_BRANCH
create-pages:
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
그런 다음 기본 브랜치(여기서는 main)에서만
job 이 실행되도록 파이프라인을 설정합니다.
default:
image: ruby:3.2
workflow:
rules:
- if: $CI_COMMIT_BRANCH
create-pages:
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
rules:
- if: $CI_COMMIT_BRANCH == "main"
배포할 Stage 지정#
GitLab CI/CD의 기본 Stage는 build, test, deploy 세 가지입니다.
프로덕션에 배포하기 전에 스크립트를 테스트하고 빌드된 사이트를 확인하고 싶다면,
기본 브랜치(여기서는 main)에 푸시할 때와
똑같이 테스트를 실행할 수 있습니다.
job 이 실행될 Stage를 지정하려면
CI 파일에 stage 줄을 추가합니다.
default:
image: ruby:3.2
workflow:
rules:
- if: $CI_COMMIT_BRANCH
create-pages:
stage: deploy
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
rules:
- if: $CI_COMMIT_BRANCH == "main"
environment: production
이제 CI 파일에 job을 하나 더 추가해, main 브랜치를 제외한 모든 브랜치의
모든 푸시를 테스트하도록 지정합니다.
default:
image: ruby:3.2
workflow:
rules:
- if: $CI_COMMIT_BRANCH
create-pages:
stage: deploy
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
rules:
- if: $CI_COMMIT_BRANCH == "main"
environment: production
test:
stage: test
script:
- gem install bundler
- bundle install
- bundle exec jekyll build -d test
artifacts:
paths:
- test
rules:
- if: $CI_COMMIT_BRANCH != "main"
test job 이 test Stage에서 실행되면 Jekyll 이
test라는 디렉터리에 사이트를 빌드합니다. 이 job은
main을 제외한 모든 브랜치에 적용됩니다.
test job은 GitLab Pages에 게시하지 않으므로 출력물은 job 아티팩트로만 저장됩니다.
빌드된 사이트를 보려면
아티팩트 아카이브의 내용을 탐색합니다.
인스턴스에서 GitLab Pages가 켜져 있으면 .html 파일을 브라우저에서 바로 미리 볼 수
있습니다. 비공개 또는 내부 프로젝트에서는 관리자가 인스턴스에
GitLab Pages 접근 제어도 켜야 합니다.
브랜치를 고유한 URL을 가진 별도의 Pages 사이트로 게시하려면 병렬 배포를 사용합니다.
여러 job에 Stage를 지정하면 같은 Stage의 job은 모두 병렬로 빌드됩니다. 웹 애플리케이션을 배포하기 전에 테스트가 여러 개 필요하다면 모든 테스트를 동시에 실행할 수 있습니다.
중복 명령 제거#
모든 job에서 같은 before_script 명령을 반복하지 않으려면 그 명령을
default 절로 옮길 수 있습니다.
이 예시에서는 gem install bundler와 bundle install 이
create-pages와 test 두 job에서 모두 실행되고 있었습니다.
이 명령을 default 절로 옮깁니다.
default:
image: ruby:3.2
before_script:
- gem install bundler
- bundle install
workflow:
rules:
- if: $CI_COMMIT_BRANCH
create-pages:
stage: deploy
script:
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
rules:
- if: $CI_COMMIT_BRANCH == "main"
environment: production
test:
stage: test
script:
- bundle exec jekyll build -d test
artifacts:
paths:
- test
rules:
- if: $CI_COMMIT_BRANCH != "main"
의존성 캐싱으로 빌드 속도 높이기#
빌드 속도를 높이려면 cache 파라미터로 프로젝트 의존성의
설치 파일을 캐시할 수 있습니다.
다음 예시는 bundle install을 실행할 때 Jekyll 의존성을
vendor 디렉터리에 캐시합니다.
default:
image: ruby:3.2
before_script:
- gem install bundler
- bundle install --path vendor
cache:
paths:
- vendor/
workflow:
rules:
- if: $CI_COMMIT_BRANCH
create-pages:
stage: deploy
script:
- bundle exec jekyll build -d public
pages: true # specifies that this is a Pages job and publishes the default public directory
rules:
- if: $CI_COMMIT_BRANCH == "main"
environment: production
test:
stage: test
script:
- bundle exec jekyll build -d test
artifacts:
paths:
- test
rules:
- if: $CI_COMMIT_BRANCH != "main"
이 경우 Jekyll 이 빌드하는 폴더 목록에서 /vendor
디렉터리를 제외해야 합니다. 그렇지 않으면 Jekyll 이
사이트와 함께 그 디렉터리 내용까지 빌드하려 합니다.
루트 디렉터리에 _config.yml 파일을 만들고
다음 내용을 추가합니다.
exclude:
- vendor
이제 GitLab CI/CD는 웹사이트를 빌드할 뿐 아니라 다음도 수행합니다.
- 기능 브랜치에 푸시할 때마다 테스트를 이어서 실행합니다.
- Bundler로 설치한 의존성을 캐시합니다.
main브랜치에 푸시할 때마다 지속적으로 배포합니다.
사이트용으로 생성된 HTML과 그 밖의 자산을 보려면 job 아티팩트를 내려받습니다.
이 페이지의 예시는 사용자 정의 job 이름을 사용합니다.