튜토리얼: GitLab을 사용하여 Hugo 사이트를 빌드, 테스트 및 배포하기

이 튜토리얼에서는 CI/CD 파이프라인을 만들어 Hugo 사이트를 빌드, 테스트 및 배포하는 과정을 안내합니다.

튜토리얼이 끝나면 작동하는 파이프라인과 Hugo 사이트가 GitLab Pages에 배포될 것입니다.

다음은 수행할 작업 개요입니다:

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

시작하기 전에

GitLab.com의 계정이 있어야 합니다.
Git을 잘 알고 계셔야 합니다.
Hugo 사이트가 있어야 합니다(아직 없는 경우 Hugo 빠른 시작을 따를 수 있습니다).

Hugo 사이트 준비

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

GitLab은 사이트를 빌드하므로 별도로 빌드하지 마세요. 실제로 public 폴더를 올리지 않는 것이 중요합니다. 이는 나중에 충돌을 일으킬 수 있습니다.

public 폴더를 제외하는 가장 쉬운 방법은 .gitignore 파일을 만들고 public 폴더를 추가하는 것입니다.

다음 명령을 사용하여 Hugo 프로젝트의 최상위에서 이 작업을 수행할 수 있습니다.

echo "/public/" >> .gitignore

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

이제 GitLab 프로젝트를 만든 후에 Hugo 사이트를 푸시할 준비가 되었습니다.

GitLab 프로젝트 생성

이전 단계에서 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 폴더를 제외한 모든 컨텐츠가 표시될 것입니다. .gitignore 파일에 의해 public 폴더가 제외됐습니다.

다음 단계에서는 CI/CD 파이프라인을 사용하여 사이트를 빌드하고 public 폴더를 재생성할 것입니다.

Hugo 사이트 빌드

GitLab을 사용하여 Hugo 사이트를 빌드하려면 우선 CI/CD 파이프라인에 대한 지침을 지정하는 .gitlab-ci.yml 파일을 만들어야 합니다. 이 전에 한 적이 없다면 처음에는 조금 어려워보일 수 있지만, GitLab에서 필요한 모든 것을 제공합니다.

구성 옵션 추가

구성 옵션은 특별한 파일인 .gitlab-ci.yml에 지정합니다. .gitlab-ci.yml 파일을 만들려면 다음을 수행하세요.

왼쪽 사이드바에서 코드 > 저장소를 선택합니다.
파일 목록 상단에서 더하기 아이콘 ( + )을 선택한 후 드롭다운 목록에서 새 파일을 선택합니다.
파일 이름에 .gitlab-ci.yml을 입력합니다. 처음의 점을 누락하지 않도록 주의하세요.
템플릿 적용 드롭다운 목록을 선택하고, “Hugo”를 필터 상자에 입력합니다.
Hugo 결과를 선택하면 Hugo 사이트를 빌드하기 위한 모든 코드가 파일에 자동으로 추가됩니다.

이 .gitlab-ci.yml 파일에서 무엇이 일어나는지 자세히 살펴보겠습니다.

default:
  image: "${CI_TEMPLATE_REGISTRY_HOST}/pages/hugo:latest"

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:  # 사이트를 빌드하고 테스트합니다.
  script:
    - hugo
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

pages:  # 정적 사이트 생성 및 지정된 경로에 저장하는 미리 정의된 작업입니다.
  script:
    - hugo
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

image는 Hugo를 포함하는 GitLab 레지스트리에서 이미지를 지정합니다. 이 이미지는 사이트가 빌드되는 환경을 만드는 데 사용됩니다.
GIT_SUBMODULE_STRATEGY 변수는 Hugo 테마에 사용되는 경우가 있는 Git 서브모듈도 GitLab에서 확인하도록 합니다.
test는 사이트에 테스트를 실행하는 작업입니다. 이 테스트 작업은 기본 브랜치가 아닌 경우를 제외하고 항상 실행됩니다. script 아래에 명령을 추가합니다. 이 작업의 명령인 hugo는 사이트를 빌드하여 테스트할 수 있습니다.
pages는 정적 사이트 생성을 위한 미리 정의된 작업입니다. 이 작업 또한 hugo 명령을 실행하여 사이트를 빌드합니다. 그런 다음 artifacts에서 이러한 결과 페이지들이 public이라는 디렉토리에 추가되도록 지정합니다. rules를 사용하여 이 커밋이 기본 브랜치에 작성되었는지 확인합니다. 보통 라이브 사이트를 다른 브랜치에서 빌드 및 배포하지 않습니다.

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

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

Hugo 사이트를 배포하고 확인하기

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

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

GitLab이 test와 pages 작업을 실행한 것을 볼 수 있을 것입니다.

사이트를 확인하려면, 왼쪽 탐색에서 설정 > Pages를 선택합니다.

파이프라인의 pages 작업은 public 디렉토리의 내용을 GitLab Pages로 배포했습니다. 페이지 액세스에서는 다음 형식의 링크를 확인할 수 있어야 합니다: https://<your-namespace>.gitlab.io/<project-path>.

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

표시된 링크를 선택하여 사이트를 확인하세요.

Hugo 사이트를 처음으로 확인할 때 스타일시트가 작동하지 않을 것입니다. 걱정하지 마세요. Hugo 설정 파일에 작은 변경을 해야 합니다. Hugo는 GitLab Pages 사이트의 URL을 알아야 스타일시트와 기타 에셋에 대한 상대적 링크를 작성할 수 있습니다.

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

파이프라인이 완료되면 방금 지정한 URL에서 사이트가 작동해야 합니다.

Hugo 사이트가 비공개 저장소에 저장된 경우, 페이지 사이트가 표시되려면 권한을 변경해야 합니다. 그렇지 않으면 인증된 사용자만 페이지 사이트를 볼 수 있습니다. 권한을 변경하려면:

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

이제 모든 사람이 볼 수 있습니다.

GitLab을 사용하여 Hugo 사이트를 빌드, 테스트, 배포했습니다. 멋진 작업입니다!

사이트를 변경하고 GitLab에 푸시할 때마다 사이트는 자동으로 빌드, 테스트, 배포됩니다.

CI/CD 파이프라인에 대해 더 알아보려면 이 복잡한 파이프라인을 생성하는 튜토리얼을 참조하세요. 또는 사용 가능한 다양한 테스트 유형에 대해 더 알아보세요.