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

이 튜토리얼은 CI/CD 파이프라인을 만들어 Hugo 사이트를 빌드하고 테스트하며 배포하는 방법을 안내합니다.

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

다음은 진행할 작업에 대한 개요입니다:

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 프로젝트 생성하기

아직 하지 않았다면, 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 리포지토리의 원격 오리진이 GitLab 프로젝트와 일치하는지 확인하세요.

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

git push origin main

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

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

Hugo 사이트 구축하기

GitLab을 사용하여 Hugo 사이트를 구축하려면 먼저 CI/CD 파이프라인에 대한 지침을 지정하는 .gitlab-ci.yml 파일을 생성해야 합니다. 이전에 이러한 작업을 해본 적이 없다면 다소 벅차게 느껴질 수 있습니다. 그러나 GitLab은 필요한 모든 것을 제공합니다.

구성 옵션 추가하기

구성 옵션은 .gitlab-ci.yml이라는 특수 파일에 지정합니다. .gitlab-ci.yml 파일을 생성하려면:

왼쪽 사이드바에서 Code > Repository를 선택합니다.
파일 목록 위에서, 플러스 아이콘( + )을 선택한 다음 드롭다운 목록에서 New file을 선택합니다.
파일 이름에 .gitlab-ci.yml을 입력합니다. 시작 부분의 마침표를 생략하지 마세요.
Apply a template 드롭다운 목록을 선택한 다음 필터 박스에 “Hugo”를 입력합니다.
결과에서 Hugo를 선택하면 파일이 CI/CD를 사용하여 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 Registry의 이미지를 지정합니다. 이 이미지는 사이트가 빌드되는 환경을 생성하는 데 사용됩니다.
GIT_SUBMODULE_STRATEGY 변수는 GitLab이 때때로 Hugo 테마에 사용되는 Git 서브모듈도 확인하도록 보장합니다.
test는 배포 전에 Hugo 사이트에서 테스트를 실행할 수 있는 작업입니다. 테스트 작업은 모든 경우에 실행됩니다. 단, 기본 브랜치에 변경 사항을 커밋하는 경우는 제외됩니다. script 아래에 모든 명령을 배치합니다. 이 작업의 명령인 hugo는 사이트를 빌드하여 테스트할 수 있도록 합니다.
pages는 Static Site Generators에서 페이지를 만드는 사전 정의된 작업입니다. 이 작업은 사이트를 빌드하기 위해 다시 hugo 명령을 실행합니다. 그런 다음 artifacts는 결과 페이지가 public이라는 디렉터리에 추가된다고 지정합니다. rules를 통해 이 커밋이 기본 브랜치에서 이루어졌는지 확인하고 있습니다. 일반적으로 다른 브랜치에서 실시간 사이트를 빌드하고 배포하고 싶지 않을 것입니다.

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

이제 Hugo 사이트를 빌드하기 위한 파이프라인이 시작되었습니다!

Hugo 사이트 배포 및 보기

빠르게 진행하면 GitLab이 귀하의 사이트를 빌드하고 배포하는 모습을 볼 수 있습니다.

왼쪽 탐색에서 Build > Pipelines를 선택하세요.

GitLab이 test 및 pages 작업을 실행한 것을 확인할 수 있습니다.

사이트를 보려면 왼쪽 탐색에서 Settings > Pages를 선택하세요.

파이프라인의 pages 작업은 public 디렉터리의 내용을 GitLab Pages에 배포했습니다. Access 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 사이트가 보일 수 있도록 권한을 변경해야 합니다. 그렇지 않으면 승인된 사용자만 볼 수 있습니다. 권한을 변경하려면:

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

이제 모든 사용자가 볼 수 있습니다.

GitLab을 사용하여 Hugo 사이트를 구축하고, 테스트하고, 배포했습니다. 훌륭한 작업입니다!

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

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