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

요약

이 튜토리얼은 Jekyll 정적 사이트 생성기(SSG)를 사용하여 처음부터 Pages 사이트를 만드는 방법을 보여줍니다. 이 예시에서는 Jekyll을 사용하지만, 다른 SSG도 유사한 단계를 따릅니다. 일반 HTML로 Pages 사이트를 만들려면 CI/CD 템플릿에서 GitLab Pages 웹사이트 만들기 튜토리얼을 참조하세요.

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

이 예시에서는 Jekyll을 사용하지만, 다른 SSG도 유사한 단계를 따릅니다. 이 튜토리얼을 완료하기 위해 Jekyll이나 SSG에 익숙할 필요는 없습니다.

Note

일반 HTML로 Pages 사이트를 만들려면 CI/CD 템플릿에서 GitLab Pages 웹사이트 만들기 튜토리얼을 참조하세요. 사용 가능한 템플릿 목록은 프로젝트 템플릿을 참조하세요.

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

1단계: 프로젝트 파일 만들기
2단계: Docker 이미지 선택
3단계: Jekyll 설치
4단계: 출력을 위한 public 디렉토리 지정
5단계: 아티팩트를 위한 public 디렉토리 지정
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 파일 시작 부분에 다음 CI/CD 구성을 추가하여 파이프라인에 기본 이미지를 추가합니다:

default:
  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로 웹사이트를 배포하려 한다는 것을 알립니다:

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build
  pages: true  # specifies that this is a Pages 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` 디렉토리 지정#

히스토리

GitLab 17.10에서 Pages 작업에 한해 pages.publish 경로를 artifacts:paths에 자동으로 추가하는 기능이 도입됨.

이제 Jekyll이 파일을 public 디렉토리로 출력했으므로, 러너가 해당 파일을 어디서 가져올지 알아야 합니다. GitLab 17.10 이상에서는 Pages 작업에 한해 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 작업이 성공적으로 완료되면 파이프라인 보기에 특별한 pages:deploy 작업이 나타납니다. 이는 GitLab Pages 데몬을 위해 웹사이트 콘텐츠를 준비합니다. GitLab이 백그라운드에서 실행하며 러너를 사용하지 않습니다.

CI/CD 파일의 기타 옵션#

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

다음 항목에서는 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)에서만 작업을 실행하도록 파이프라인을 구성합니다.

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"

배포 스테이지 지정#

GitLab CI/CD의 세 가지 기본 스테이지는 build, test, deploy입니다.

스크립트를 테스트하고 프로덕션에 배포하기 전에 빌드된 사이트를 확인하려면, 기본 브랜치(여기서는 main)에 푸시할 때와 동일하게 테스트를 실행할 수 있습니다.

작업이 실행될 스테이지를 지정하려면 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 파일에 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 작업이 test 스테이지에서 실행되면 Jekyll이 test라는 디렉토리에 사이트를 빌드합니다. 이 작업은 main을 제외한 모든 브랜치에 영향을 미칩니다.

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

중복 명령 제거#

모든 작업에서 동일한 before_script 명령을 중복하지 않으려면 default 섹션에 추가할 수 있습니다.

예시에서 gem install bundler와 bundle install은 pages 및 test 두 작업 모두에서 실행되고 있었습니다.

이 명령들을 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 및 기타 자산을 보려면 작업 아티팩트를 다운로드하세요.

이 페이지의 예시는 사용자 정의 작업 이름을 사용합니다.

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

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

원문 보기

번역일: 2026-05-22

요약

이 예시에서는 Jekyll을 사용하지만, 다른 SSG도 유사한 단계를 따릅니다. 이 튜토리얼을 완료하기 위해 Jekyll이나 SSG에 익숙할 필요는 없습니다.

Note

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

1단계: 프로젝트 파일 만들기
2단계: Docker 이미지 선택
3단계: Jekyll 설치
4단계: 출력을 위한 public 디렉토리 지정
5단계: 아티팩트를 위한 public 디렉토리 지정
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 파일 시작 부분에 다음 CI/CD 구성을 추가하여 파이프라인에 기본 이미지를 추가합니다:

default:
  image: ruby:3.2

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로 웹사이트를 배포하려 한다는 것을 알립니다:

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build
  pages: true  # specifies that this is a Pages 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` 디렉토리 지정#

히스토리

GitLab 17.10에서 Pages 작업에 한해 pages.publish 경로를 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 웹사이트 링크를 찾습니다.

CI/CD 파일의 기타 옵션#

다음 항목에서는 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)에서만 작업을 실행하도록 파이프라인을 구성합니다.

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"

배포 스테이지 지정#

GitLab CI/CD의 세 가지 기본 스테이지는 build, test, deploy입니다.

작업이 실행될 스테이지를 지정하려면 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 파일에 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"

중복 명령 제거#

모든 작업에서 동일한 before_script 명령을 중복하지 않으려면 default 섹션에 추가할 수 있습니다.

예시에서 gem install bundler와 bundle install은 pages 및 test 두 작업 모두에서 실행되고 있었습니다.

이 명령들을 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"

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

exclude:
  - vendor

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

기능 브랜치에 지속적 테스트로 푸시합니다.
Bundler로 설치된 의존성을 캐시합니다.
main 브랜치에 대한 모든 푸시를 지속적으로 배포합니다.

사이트에 대해 생성된 HTML 및 기타 자산을 보려면 작업 아티팩트를 다운로드하세요.

이 페이지의 예시는 사용자 정의 작업 이름을 사용합니다.

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

전제 조건#

프로젝트 파일 만들기#

Docker 이미지 선택#

Jekyll 설치#

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

아티팩트를 위한 `public` 디렉토리 지정#

웹사이트 배포 및 보기#

CI/CD 파일의 기타 옵션#

Pages 사이트에 특정 브랜치 배포#

배포 스테이지 지정#

중복 명령 제거#

캐시된 의존성으로 더 빠르게 빌드#

관련 주제#

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

전제 조건#

프로젝트 파일 만들기#

Docker 이미지 선택#

Jekyll 설치#

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

아티팩트를 위한 `public` 디렉토리 지정#

웹사이트 배포 및 보기#

CI/CD 파일의 기타 옵션#

Pages 사이트에 특정 브랜치 배포#

배포 스테이지 지정#

중복 명령 제거#

캐시된 의존성으로 더 빠르게 빌드#

관련 주제#

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

전제 조건#

프로젝트 파일 만들기#

Docker 이미지 선택#

Jekyll 설치#

출력을 위한 public 디렉토리 지정#

아티팩트를 위한 public 디렉토리 지정#

웹사이트 배포 및 보기#

CI/CD 파일의 기타 옵션#

Pages 사이트에 특정 브랜치 배포#

배포 스테이지 지정#

중복 명령 제거#

캐시된 의존성으로 더 빠르게 빌드#

관련 주제#

전제 조건#

프로젝트 파일 만들기#

Docker 이미지 선택#

Jekyll 설치#

출력을 위한 public 디렉토리 지정#

아티팩트를 위한 public 디렉토리 지정#

웹사이트 배포 및 보기#

CI/CD 파일의 기타 옵션#

Pages 사이트에 특정 브랜치 배포#

배포 스테이지 지정#

중복 명령 제거#

캐시된 의존성으로 더 빠르게 빌드#

관련 주제#

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

아티팩트를 위한 `public` 디렉토리 지정#

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

아티팩트를 위한 `public` 디렉토리 지정#