준비 사항
프로젝트 파일 만들기
Docker 이미지 선택
Jekyll 설치
출력을 위한 public 디렉터리 지정
artifacts를 위한 public 디렉터리 지정
웹사이트를 배포하고 보기
CI/CD 파일을 위한 다른 옵션
관련 주제

튜토리얼: GitLab Pages 웹사이트를 처음부터 만들기

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

이 튜토리얼에서는 Jekyll 정적 사이트 생성기(SSG)를 사용하여 처음부터 페이지 사이트를 만드는 방법을 보여줍니다. 빈 프로젝트에서 시작하여 자체 CI/CD 구성 파일을 작성하고, 이 파일은 러너(runner)에 지시를 제공합니다. CI/CD 파이프라인이 실행되면 페이지 사이트가 생성됩니다.

이 예제에서는 Jekyll을 사용하지만, 다른 SSGs도 유사한 단계를 따릅니다. Jekyll이나 SSG에 익숙하지 않아도 이 튜토리얼을 완료할 수 있습니다.

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

단계 1: 프로젝트 파일 만들기
단계 2: Docker 이미지 선택
단계 3: Jekyll 설치
단계 4: public 디렉터리로의 출력 지정
단계 5: public 디렉터리로의 artifacts 지정
단계 6: 웹사이트를 배포하고 보기

준비 사항

GitLab에 빈 프로젝트가 있어야 합니다.

프로젝트 파일 만들기

루트(최상위) 디렉터리에 세 개의 파일을 만듭니다:

.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 파일을 편집하고 첫 번째 줄로 이 텍스트를 추가합니다:

image: ruby:3.2

SSG가 빌드에 NodeJS가 필요한 경우, 파일 시스템의 일부로 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라고 합니다. 이 설정은 러너에게 작업을 사용하여 GitLab Pages로 웹사이트를 배포하도록 요청합니다:

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build

출력을 위한 `public` 디렉터리 지정

Jekyll은 출력을 생성할 위치를 알아야 합니다. GitLab Pages는 public이라는 디렉터리의 파일만을 고려합니다.

Jekyll은 빌드된 웹사이트의 출력 디렉터리를 지정하기 위해 destination flag (-d)를 사용합니다. .gitlab-ci.yml 파일에 destination을 추가합니다:

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public

artifacts를 위한 `public` 디렉터리 지정

이제 Jekyll이 파일을 public 디렉터리로 출력했으므로, 러너는 이들을 가져올 위치를 알아야 합니다. artifacts는 public 디렉터리에 저장됩니다:

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

여러분의 .gitlab-ci.yml 파일은 이제 다음과 같아야 합니다:

image: ruby:3.2

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

웹사이트를 배포하고 보기

앞에서 언급한 단계를 완료한 후 웹사이트를 배포합니다:

.gitlab-ci.yml 파일을 저장 및 커밋합니다.
Build > 파이프라인으로 이동하여 파이프라인을 확인합니다.
파이프라인이 완료되면 배포 > Pages로 이동하여 페이지 웹사이트의 링크를 찾습니다.

이 pages 작업이 성공적으로 완료되면 특별한 pages:deploy 작업이 파이프라인보기에 나타납니다. 이는 웹사이트 콘텐츠를 GitLab Pages 데몬에 맞게 준비합니다. GitLab은 이를 백그라운드에서 실행하며 러너를 사용하지 않습니다.

CI/CD 파일을 위한 다른 옵션

더 고급 작업을 수행하려면 다른 CI/CD YAML 키워드로 .gitlab-ci.yml 파일을 업데이트할 수 있습니다. GitLab에 포함된 CI Lint 도구를 사용하여 .gitlab-ci.yml 파일을 유효성을 검사할 수 있습니다.

다음 주제에서는 CI/CD 파일에 추가할 수 있는 다른 옵션의 예제를 보여줍니다.

특정 브랜치를 페이지 사이트로 배포

특정 브랜치에서만 페이지 사이트로 배포하려는 경우가 있을 수 있습니다.

먼저, 변경 사항이 푸시될 때에만 파이프라인이 실행되도록 workflow 섹션을 추가합니다:

image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

그런 다음, 파이프라인이 기본 브랜치인 default branch(여기서 main)에 대해서만 작업을 실행하도록 구성합니다.

image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

배포할 단계 지정

GitLab CI/CD에는 빌드(build), 테스트(test), 그리고 배포(deploy) 세 가지 기본 단계가 있습니다.

프로덕션으로 배포하기 전에 스크립트를 테스트하고 빌드된 사이트를 확인하려면, default branch(여기서 main)으로 푸시될 때와 동일하게 테스트를 실행하려고 합니다.

작업이 실행될 단계를 명시하려면 CI 파일에 stage 라인을 추가합니다:

image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

이제 ‘test’ 브랜치를 제외한 모든 브랜치에 대해 푸시될 때 test 작업을 실행하도록 CI 파일에 다른 작업을 추가합니다:

image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  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 작업이 test 단계에서 실행될 때, Jekyll은 test라는 디렉터리에 사이트를 빌드합니다. 이 작업은 main을 제외한 모든 브랜치에 영향을 미칩니다.

다른 작업에 단계를 적용하면, 동일한 단계에 있는 모든 작업이 병렬로 빌드됩니다. 웹 애플리케이션이 배포되기 전에 하나 이상의 테스트가 필요한 경우, 모든 테스트를 동시에 실행할 수 있습니다.

중복 명령 제거

각 작업에서 동일한 스크립트를 중복으로 작성하는 것을 피하려면, before_script 섹션에 스크립트를 추가할 수 있습니다.

예를 들어, gem install bundler와 bundle install은 pages와 test 두 작업에 대해 실행되고 있었습니다.

이러한 명령을 before_script 섹션으로 이동합니다:

image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

before_script:
  - gem install bundler
  - bundle install

pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  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 디렉터리에 캐시합니다:

image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

cache:
  paths:
    - vendor/

before_script:
  - gem install bundler
  - bundle install --path vendor

pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  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"

이 경우, /vendor 디렉터리를 Jekyll이 빌드할 폴더 디렉터리에서 제외해야 합니다. 그렇지 않으면 Jekyll이 사이트와 함께 디렉터리 내용을 빌드하려고 시도합니다.

루트 디렉터리에 _config.yml이라는 파일을 만들고 다음 내용을 추가합니다:

exclude:
  - vendor

이제 GitLab CI/CD는 웹사이트를 빌드하는 것뿐만 아니라:

기능 브랜치로의 지속적인 테스트 푸시
Bundler로 설치된 캐시된 의존성
main 브랜치로의 각 푸시의 지속적인 배포

만을 수행합니다.

웹사이트에서 생성된 HTML 및 기타 에셋을 확인하려면, 작업 아티팩트 다운로드를 참고하세요.

튜토리얼: GitLab Pages 웹사이트를 처음부터 만들기

준비 사항

프로젝트 파일 만들기

Docker 이미지 선택

Jekyll 설치

출력을 위한 `public` 디렉터리 지정

artifacts를 위한 `public` 디렉터리 지정

웹사이트를 배포하고 보기

CI/CD 파일을 위한 다른 옵션

특정 브랜치를 페이지 사이트로 배포

배포할 단계 지정

중복 명령 제거

캐시된 의존성을 사용하여 더 빠르게 빌드

관련 주제

도움말

기능 사용 가능성과 제품 평가판

도움받기

튜토리얼: GitLab Pages 웹사이트를 처음부터 만들기

준비 사항

프로젝트 파일 만들기

Docker 이미지 선택

Jekyll 설치

출력을 위한 public 디렉터리 지정

artifacts를 위한 public 디렉터리 지정

웹사이트를 배포하고 보기

CI/CD 파일을 위한 다른 옵션

특정 브랜치를 페이지 사이트로 배포

배포할 단계 지정

중복 명령 제거

캐시된 의존성을 사용하여 더 빠르게 빌드

관련 주제

도움말

기능 사용 가능성과 제품 평가판

도움받기

출력을 위한 `public` 디렉터리 지정

artifacts를 위한 `public` 디렉터리 지정