튜토리얼: GitLab으로 Hugo 사이트 빌드, 테스트, 배포하기

요약

이 튜토리얼에서는 Hugo 사이트를 빌드, 테스트, 배포하는 CI/CD 파이프라인을 생성합니다. 튜토리얼을 마치면 작동하는 파이프라인과 GitLab Pages에 배포된 Hugo 사이트를 갖추게 됩니다. 수행할 작업의 개요는 다음과 같습니다.

이 튜토리얼에서는 Hugo 사이트를 빌드, 테스트, 배포하는 CI/CD 파이프라인을 생성합니다.

튜토리얼을 마치면 작동하는 파이프라인과 GitLab Pages에 배포된 Hugo 사이트를 갖추게 됩니다.

수행할 작업의 개요는 다음과 같습니다.

Hugo 사이트를 준비합니다.
GitLab 프로젝트를 생성합니다.
Hugo 사이트를 GitLab에 푸시합니다.
CI/CD 파이프라인으로 Hugo 사이트를 빌드합니다.
GitLab Pages로 Hugo 사이트를 배포합니다.

시작하기 전에#

GitLab.com 계정
Git에 대한 이해
Hugo 사이트(아직 없다면 Hugo Quick Start를 참고합니다)

Hugo 사이트 준비#

먼저 Hugo 사이트가 GitLab에 푸시할 준비가 되었는지 확인합니다. 콘텐츠, 테마, Hugo 설정 파일이 있어야 합니다.

사이트를 직접 빌드하지 않습니다. GitLab이 대신 빌드하기 때문입니다. 실제로 public 폴더를 업로드하지 않는 것이 중요합니다. 나중에 충돌을 일으킬 수 있기 때문입니다.

public 폴더를 제외하는 가장 쉬운 방법은 .gitignore 파일을 생성하고 public/이라는 텍스트로 새 줄을 추가하는 것입니다.

Hugo 프로젝트의 최상위 디렉터리에서 다음 명령으로 이 작업을 수행할 수 있습니다.

echo "public/" >> .gitignore

이 명령은 public/을 새 .gitignore 파일에 추가하거나 기존 파일에 덧붙입니다.

이제 GitLab 프로젝트를 생성하고 나면 Hugo 사이트를 푸시할 준비가 됩니다.

GitLab 프로젝트 생성#

아직 하지 않았다면 Hugo 사이트를 위한 빈 GitLab 프로젝트를 생성합니다.

빈 프로젝트를 생성하려면 GitLab에서 다음을 수행합니다.

오른쪽 위 모서리에서 Create new(+)를 선택한 다음 New project/repository를 선택합니다.
Create blank project를 선택합니다.
프로젝트 세부 정보를 입력합니다.
- Project name 텍스트 상자에 프로젝트 이름을 입력합니다. 이름은 소문자 또는 대문자(a-zA-Z), 숫자(0-9), 이모지, 밑줄(_)로 시작해야 합니다. 마침표(.), 더하기 기호(+), 대시(-), 공백도 포함할 수 있습니다.
- Project slug 텍스트 상자에 프로젝트 경로를 입력합니다. GitLab 인스턴스는 슬러그를 프로젝트의 URL 경로로 사용합니다. 슬러그를 변경하려면 먼저 프로젝트 이름을 입력한 다음 슬러그를 변경합니다.
- Visibility Level은 Private 또는 Public 중 하나로 설정할 수 있습니다. Private을 선택해도 웹사이트는 공개적으로 이용할 수 있지만 코드는 비공개로 유지됩니다.
- 기존 리포지터리를 푸시할 것이므로 Initialize repository with a README 확인란을 선택 해제합니다.
준비가 되면 Create project를 선택합니다.
이 새 프로젝트에 코드를 푸시하는 방법에 대한 안내가 표시됩니다. 이 안내는 다음 단계에서 필요합니다.

이제 Hugo 사이트를 위한 저장 공간이 마련되었습니다.

Hugo 사이트를 GitLab에 푸시#

다음으로 로컬 Hugo 사이트를 원격 GitLab 프로젝트에 푸시해야 합니다.

이전 단계에서 새 GitLab 프로젝트를 생성했다면 리포지터리를 초기화한 다음 파일을 커밋하고 푸시하는 방법에 대한 안내가 표시됩니다.

그렇지 않다면 로컬 Git 리포지터리의 원격 origin이 GitLab 프로젝트와 일치하는지 확인합니다.

기본 브랜치가 main이라고 가정하면 다음 명령으로 Hugo 사이트를 푸시할 수 있습니다.

git push origin main

사이트를 푸시하고 나면 public 폴더를 제외한 모든 콘텐츠가 표시됩니다. public 폴더는 .gitignore 파일에 의해 제외되었습니다.

다음 단계에서는 CI/CD 파이프라인을 사용해 사이트를 빌드하고 public 폴더를 다시 생성합니다.

CI/CD 파이프라인으로 Hugo 사이트 빌드#

GitLab으로 Hugo 사이트를 빌드하려면 먼저 CI/CD 파이프라인의 지침을 지정하는 .gitlab-ci.yml 파일을 생성해야 합니다. 이전에 해본 적이 없다면 어렵게 느껴질 수 있습니다. 하지만 GitLab이 필요한 모든 것을 제공합니다.

아래에 표시된 .gitlab-ci.yml 파일을 사용하려면 hugo.toml 파일에도 일치하는 테마 경로가 지정되어 있는지 확인합니다. 아래의 예시 hugo.toml 파일은 GitLab Pages 프로젝트의 baseURL 설정도 보여줍니다.

baseURL = 'https://<your-namespace>.gitlab.io/<project-path>'
languageCode = 'en-us'
title = 'Hugo on GitLab'
[module]
[[module.imports]]
  path = 'github.com/adityatelange/hugo-PaperMod'

GitLab 설정 옵션 추가#

설정 옵션은 .gitlab-ci.yml이라는 특수 파일에 지정합니다.

Hugo 템플릿을 사용해 .gitlab-ci.yml 파일을 생성하려면 다음을 수행합니다.

왼쪽 사이드바에서 Code > Repository를 선택합니다.
파일 목록 위에서 더하기 아이콘( + )을 선택한 다음 드롭다운 목록에서 New file을 선택합니다.
파일 이름으로 .gitlab-ci.yml을 입력합니다. 앞에 있는 마침표를 빠뜨리지 않습니다.
Apply a template 드롭다운 목록을 선택한 다음 필터 상자에 "Hugo"를 입력합니다.
검색 결과 Hugo를 선택하면 CI/CD로 Hugo 사이트를 빌드하는 데 필요한 모든 코드가 파일에 채워집니다.

이 .gitlab-ci.yml 파일에서 어떤 일이 일어나는지 자세히 살펴봅니다.

default:
  image: "hugomods/hugo:exts"

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  THEME_URL: "github.com/adityatelange/hugo-PaperMod"

test:  # builds and tests your site
  script:
    - hugo
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

create-pages:  # a user-defined job that builds your pages and saves them to the specified path.
  script:
    - hugo
  pages: true  # specifies that this is a Pages job
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

image는 Hugo가 포함된 GitLab Registry의 이미지를 지정합니다. 이 이미지는 사이트가 빌드되는 환경을 생성하는 데 사용됩니다.
GIT_SUBMODULE_STRATEGY 변수는 GitLab이 Hugo 테마에 종종 사용되는 Git 서브모듈도 확인하도록 합니다.
test는 배포되기 전에 Hugo 사이트에 대한 테스트를 실행할 수 있는 job입니다. test job은 기본 브랜치에 변경 사항을 커밋하는 경우를 제외한 모든 경우에 실행됩니다. 명령은 script 아래에 배치합니다. 이 job의 명령인 hugo는 테스트할 수 있도록 사이트를 빌드합니다.
create-pages는 정적 사이트 생성기로 페이지를 생성하는 사용자 정의 job입니다. 이 job도 user-defined job names를 사용하며 hugo 명령을 실행해 사이트를 빌드합니다. 그런 다음 pages: true는 이것이 Pages job임을 지정하고, artifacts는 결과로 생성된 페이지가 public이라는 디렉터리에 추가됨을 지정합니다. rules를 사용하면 이 커밋이 기본 브랜치에서 이루어졌는지 확인합니다. 일반적으로 다른 브랜치에서 라이브 사이트를 빌드하고 배포하는 것은 바람직하지 않습니다.

이 파일에 다른 내용을 추가할 필요는 없습니다. 준비가 되면 페이지 상단의 Commit changes를 선택합니다.

방금 Hugo 사이트를 빌드하는 파이프라인을 트리거했습니다.

GitLab Pages로 Hugo 사이트 배포#

빠르게 확인하면 GitLab이 사이트를 빌드하고 배포하는 과정을 볼 수 있습니다.

왼쪽 사이드바에서 Build > Pipelines를 선택합니다.

GitLab이 test job과 create-pages job을 실행한 것을 확인할 수 있습니다.

사이트를 확인하려면 파이프라인이 완료된 후 왼쪽 사이드바에서 Deploy > Pages를 선택해 Pages 웹사이트 링크를 찾습니다.

Hugo 설정 옵션 추가#

Hugo 사이트를 처음 확인하면 스타일시트가 작동하지 않습니다. 걱정하지 않아도 됩니다. Hugo 설정 파일에서 약간의 변경만 하면 됩니다. Hugo는 스타일시트와 기타 에셋에 대한 상대 링크를 빌드할 수 있도록 GitLab Pages 사이트의 URL을 알아야 합니다.

로컬 Hugo 사이트에서 최신 변경 사항을 풀한 다음 config.yaml 또는 config.toml 파일을 엽니다.
BaseURL 매개변수의 값을 GitLab Pages 설정에 표시된 URL과 일치하도록 변경합니다.
변경한 파일을 GitLab에 푸시하면 파이프라인이 다시 트리거됩니다.

GitLab Pages URL 찾기#

파이프라인이 완료되면 Deploy > Pages로 이동해 Pages 웹사이트 링크를 찾습니다.

파이프라인의 pages job이 public 디렉터리의 콘텐츠를 GitLab Pages에 배포했습니다. Access pages 아래에서 https://<your-namespace>.gitlab.io/<project-path> 형식의 링크를 확인할 수 있습니다.

파이프라인을 아직 실행하지 않았다면 이 링크가 표시되지 않습니다.

표시된 링크를 선택해 사이트를 확인합니다. Hugo 설정의 BaseURL 설정을 GitLab 배포 URL과 일치하도록 변경해야 합니다.

GitLab Pages 공개 범위 설정#

Hugo 사이트가 비공개 리포지터리에 저장되어 있다면 Pages 사이트가 표시되도록 권한을 변경해야 합니다. 그렇지 않으면 프로젝트 멤버에게만 표시됩니다. 사이트 권한을 변경하려면 다음을 수행합니다.

Settings > General > Visibility, project features, permissions로 이동합니다.
Pages 섹션까지 아래로 스크롤한 다음 드롭다운 목록에서 Everyone을 선택합니다.
Save changes를 선택합니다.

이제 누구나 해당 URL에서 사이트를 볼 수 있습니다.

GitLab으로 Hugo 사이트를 빌드, 테스트, 배포했습니다. 수고하셨습니다.

사이트를 변경하고 GitLab에 푸시할 때마다 .gitlab-ci.yml 파일의 규칙에 따라 사이트가 자동으로 빌드, 테스트, 배포됩니다.

CI/CD 파이프라인에 대해 더 알아보려면 복잡한 파이프라인을 생성하는 방법에 대한 튜토리얼을 참고합니다. 이용 가능한 다양한 테스트 유형에 대해서도 더 알아볼 수 있습니다.