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

요약

이 튜토리얼은 Hugo 사이트를 빌드, 테스트, 배포하기 위한 CI/CD 파이프라인 만들기를 안내합니다. 튜토리얼을 마치면 작동하는 파이프라인과 GitLab Pages에 배포된 Hugo 사이트를 갖게 됩니다. 먼저 Hugo 사이트가 GitLab에 푸시할 준비가 되어 있는지 확인합니다.

이 튜토리얼은 Hugo 사이트를 빌드, 테스트, 배포하기 위한 CI/CD 파이프라인 만들기를 안내합니다.

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

수행할 작업 개요:

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

시작하기 전에#

GitLab.com 계정.
Git에 대한 친숙함.
Hugo 사이트 (아직 없다면 Hugo 빠른 시작을 따라 만들 수 있습니다).

Hugo 사이트 준비#

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

GitLab이 사이트를 빌드하므로 사이트를 직접 빌드하지 마세요. 실제로 public 폴더를 업로드하지 않는 것이 중요합니다. 나중에 충돌이 발생할 수 있습니다.

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

Hugo 프로젝트의 최상위 수준에서 다음 명령으로 이 작업을 수행할 수 있습니다:

echo "public/" >> .gitignore

이렇게 하면 새 .gitignore 파일에 public/이 추가되거나 기존 파일에 추가됩니다.

GitLab 프로젝트를 만든 후 Hugo 사이트를 푸시할 준비가 됩니다.

GitLab 프로젝트 만들기#

아직 만들지 않았다면 Hugo 사이트를 위한 빈 GitLab 프로젝트를 만드세요.

GitLab에서 빈 프로젝트를 만들려면:

오른쪽 상단 모서리에서 새로 만들기(+) 및 새 프로젝트/리포지터리를 선택합니다.
빈 프로젝트 만들기를 선택합니다.
프로젝트 세부 정보를 입력합니다:
- 프로젝트 이름 필드에 프로젝트 이름을 입력합니다. 이름은 소문자 또는 대문자(a-zA-Z), 숫자(0-9), 이모지 또는 밑줄(_)로 시작해야 합니다. 점(.), 더하기(+), 대시(-) 또는 공백도 포함할 수 있습니다.
- 프로젝트 슬러그 필드에 프로젝트 경로를 입력합니다. GitLab 인스턴스는 슬러그를 프로젝트의 URL 경로로 사용합니다. 슬러그를 변경하려면 먼저 프로젝트 이름을 입력한 다음 슬러그를 변경합니다.
- 가시성 수준은 비공개 또는 공개일 수 있습니다. 비공개를 선택하면 웹사이트는 여전히 공개적으로 접근 가능하지만 코드는 비공개로 유지됩니다.
- 기존 리포지터리를 푸시하므로 README로 리포지터리 초기화 박스를 선택 해제합니다.
준비가 되면 프로젝트 만들기를 선택합니다.
이 새 프로젝트에 코드를 푸시하기 위한 지침이 표시됩니다. 다음 단계에서 이 지침이 필요합니다.

이제 Hugo 사이트의 홈이 생겼습니다!

Hugo 사이트를 GitLab에 푸시#

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

이전 단계에서 새 GitLab 프로젝트를 만들었다면 리포지터리를 초기화한 다음 파일을 커밋하고 푸시하기 위한 지침이 표시됩니다.

그렇지 않으면 로컬 Git 리포지터리의 원격 오리진이 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 파일을 만들려면:

왼쪽 사이드바에서 코드 > 리포지터리를 선택합니다.
파일 목록 위에서 플러스 아이콘(+)을 선택한 다음 드롭다운 목록에서 새 파일을 선택합니다.
파일 이름으로 .gitlab-ci.yml을 입력합니다. 시작 부분의 마침표를 생략하지 마세요.
템플릿 적용 드롭다운 목록을 선택하고 필터 박스에 "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:  # 사이트를 빌드하고 테스트합니다
  script:
    - hugo
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

create-pages:  # 페이지를 빌드하고 지정된 경로에 저장하는 사용자 정의 job.
  script:
    - hugo
  pages: true  # 이것이 Pages job임을 지정합니다
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

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

이 파일에 다른 것을 추가할 필요가 없습니다. 준비가 되면 페이지 상단에서 변경 사항 커밋을 선택합니다.

Hugo 사이트를 빌드하기 위한 파이프라인을 방금 트리거했습니다!

GitLab Pages로 Hugo 사이트 배포#

빠르다면 GitLab이 사이트를 빌드하고 배포하는 것을 볼 수 있습니다.

왼쪽 탐색에서 빌드 > 파이프라인을 선택합니다.

GitLab이 test 및 create-pages job을 실행했음을 알 수 있습니다.

사이트를 보려면 파이프라인이 완료되면 왼쪽 탐색에서 배포 > Pages를 선택하여 Pages 웹사이트의 링크를 찾습니다.

Hugo 구성 옵션 추가#

Hugo 사이트를 처음 볼 때 스타일시트가 작동하지 않습니다. 걱정하지 마세요. Hugo 구성 파일에서 약간의 변경이 필요합니다. Hugo는 스타일시트 및 기타 에셋에 대한 상대 링크를 빌드하기 위해 GitLab Pages 사이트의 URL을 알아야 합니다:

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

GitLab Pages URL 찾기#

파이프라인이 완료되면 배포 > Pages로 이동하여 Pages 웹사이트의 링크를 찾습니다.

파이프라인의 pages job은 public 디렉토리의 내용을 GitLab Pages에 배포했습니다. Pages 접근 아래에서 https://<your-namespace>.gitlab.io/<project-path> 형식의 링크가 표시됩니다.

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

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

GitLab Pages 가시성 설정#

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

설정 > 일반 > 가시성, 프로젝트 기능, 권한으로 이동합니다.
Pages 섹션으로 스크롤하고 드롭다운 목록에서 모든 사람을 선택합니다.
변경 사항 저장을 선택합니다.

이제 모든 사람이 URL에서 사이트를 볼 수 있습니다.

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

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

CI/CD 파이프라인에 대한 자세한 내용은 복잡한 파이프라인 만들기 방법에 대한 이 튜토리얼을 시도해 보세요. 사용 가능한 다양한 테스트 유형에 대해서도 자세히 알아볼 수 있습니다.