최승은 Tech Blog

Hugo 블로그 Build 하기

지금까지 Hugo 테마를 세팅해보았고,
이제는 Github.io 블로그에 업로드 해야합니다.
그리고 업로드 전에 Build 과정이 필요합니다.

hugo 명령어를 입력하면 build가 진행되고,
public 폴더 안에 html 파일이 생성됩니다.

build가 진행된 모습

이렇게 생성된 public 폴더를 github.io에 올리면 완성입니다!
일단 과정을 말씀드리자면..

hugo build
public 폴더를 github.io repo에 연결
github.io repo에 git add → commit → push

이 과정을 배포할때마다 진행하려면 상당히 번거롭고 실수할 가능성이 있습니다.
그래서 바로 자동화를 해볼거에요.

스크립트를 작성해서 스크립트를 실행시키는 방법도 있지만,
앞으로 배포할때 아예 명령어를 사용하지 않기 위해
Github Actions로 배포를 자동화 하겠습니다!

Github Actions로 배포 자동화하기

.gitignore 설정

배포 설정을 하기에 앞서 먼저 .gitignore 설정을 해주겠습니다.

1
2
3
4
5
public
resources
assets/jsconfig.json
.hugo_build.lock
.idea

hugo 블로그 배포시 필요하지 않은 파일들을 제외하고,
public 폴더는 자동 배포 workflow에서 생성할 것이기에 제외했습니다.

Deploy Key 생성

Github Actions 스크립트를 작성하기 전에
먼저 Deploy Key를 생성 및 등록 해야합니다.

아래 명령어에 깃허브 가입한 이메일을 입력하시면 deploy key가 발급됩니다.

1
ssh-keygen -t rsa -b 4096 -C "{github_email}"

이 과정에서 입력사항이 3번 있습니다.
key를 생성할 위치를 확인하시고 엔터
비밀번호 입력 후 엔터(비밀번호 없이도 가능)
비밀번호 재입력 후 엔터

해당 위치에 id_rsa와 id_rsa.pub 파일이 생성되었습니다.
id_rsa는 private key이고 id_rsa.pub는 public key입니다.
이 두가지를 깃허브에서 입력해줍니다.

Blog Repository에 Key 세팅

먼저 blog repository에서 세팅을 하겠습니다.
Settings → Secrets and variables → Actions → New Repository Secret
Secret 이름을 입력하고 id_rsa 파일 내용을 입력합니다.
파일은 메모장으로 여셔도 확인이 가능합니다.
꼭 내용을 전부 복사해주셔야 해요!
사진 참고해주세요!

Github.io Repository에 Key 세팅

이번에는 github.io repository에서 세팅을 하겠습니다.
Settings → Deploy keys → Add deploy key
Title을 입력하고 id_rsa.pub 파일 내용을 입력합니다.
파일은 메모장으로 여셔도 확인이 가능합니다.
꼭 내용을 전부 복사해주셔야 해요!
그리고 Allow write access를 꼭 체크해주셔야
해당 repository에 push가 가능합니다!

Github Actions workflow 작성

이제 드디어 deploy key 세팅을 끝내고 workflow를 작성합니다!
blog 폴더에서 .github/workflows/deploy.yml 파일을 생성해주세요.
→ .github 폴더 안에 workflows 폴더 안에 deploy.yml 파일 생성

먼저 deploy.yml 파일에 작성할 내용을 보여드릴게요.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
name: Deploy Github.io

on:
  workflow_dispatch:
    inputs:
      commitMessage:
        description: 'Commit Message'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - name: Pull Blog Repo
        uses: actions/checkout@v3
        with:
          submodules: true

      - name: Pull Github.io Repo into public
        uses: actions/checkout@v3
        with:
          repository: cse0518/cse0518.github.io
          path: public

      - name: Remove All Except .git
        run: find ./public/* -name '.git' -prune -o -exec rm -rf {} \; -prune

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo -t hugo-theme-stack

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.DEPLOY_KEY }}
          external_repository: cse0518/cse0518.github.io
          publish_branch: main
          publish_dir: ./public
          commit_message: ${{ github.event.inputs.commitMessage }}

이렇게 작성이 완료됩니다.
내용을 하나하나 설명해볼게요!

1
2
3
4
5
6
7
8
name: Deploy Github.io # workflow의 이름 지정

on: # 언제 workflow를 실행할지 설정
  workflow_dispatch: # 직접 실행 버튼을 눌러서 실행
    inputs: # workflow를 실행할때 입력받을 내용 추가
      commitMessage: # 저는 commit message를 입력하기 위해 넣었습니다
        description: 'Commit Message' # 해당 입력값 설명
        required: true # 필수로 입력되어야 하는지 여부

해당 workflow의 이름을 Deploy Github.io라고 지어줬습니다.
그리고 저는 직접 실행 버튼을 눌러서 배포하려고 workflow_dispatch 옵션을 설정했습니다.
push 또는 PR 할때마다 자동 배포되도록 설정하려면
on: [push, pull_request] 이런식으로도 설정 가능합니다.

이런식으로 Actions 탭에서 버튼을 눌러 workflows를 실행할 수 있습니다.
그리고 input을 입력 받으면 해당 값을 workflow 안에서 활용 가능합니다.

1
2
3
4
jobs: # job들을 선언
  deploy: # deploy라는 job
    runs-on: ubuntu-20.04 # 우분투 해당 버전에서 실행
    steps: # step들을 차례대로 실행

여러개의 job을 선언하고 실행시킬 수 있습니다.
job은 순서와 상관없이 병렬로 실행됩니다.
그리고 하나의 job 안의 step들은 순서대로 실행됩니다.

1
2
3
4
      - name: Pull Blog Repo # step 이름 설정(생략 가능)
        uses: actions/checkout@v3 # 해당 repository로 checkout하여 내용을 pull 합니다.
        with:
          submodules: true # submodule을 함께 pull 합니다.

초기 우분투 환경에는 아무런 파일도 존재하지 않습니다.
그래서 해당 blog repository 파일들을 받아와야합니다.
그 과정이 actions/checkout 에서 일어납니다.

그리고 theme를 submodule로 설정했기 때문에
submodule을 함께 받아오려면 with: submodules: true 옵션을 추가해줍니다.

1
2
3
4
5
6
7
8
9
      - name: Pull Github.io Repo into public # step 이름 설정
        uses: actions/checkout@v3 # pull
        with:
          repository: cse0518/cse0518.github.io # 해당 repository를 pull 합니다.
          path: public # public 폴더 안에 가져옵니다.

      - name: Remove All Except .git # step 이름 설정
        # public 폴더 안에 .git을 제외한 모든 파일을 삭제
        run: find ./public/* -name '.git' -prune -o -exec rm -rf {} \; -prune

hugo 명령어를 통해 빌드하고 public 폴더를 github.io repo와 연동해도 되지만,
저는 반대로 public 폴더에 github.io repo를 받아오고
이후에 빌드를 하도록 했습니다.

.git 폴더를 제외하고 모든 파일을 삭제하면서 기존 파일은 삭제하고, 새롭게 빌드합니다.

1
2
3
4
5
6
7
8
      - name: Setup Hugo # step 이름 설정
        uses: peaceiris/actions-hugo@v2 # hugo를 설치하는 오픈 소스
        with:
          hugo-version: 'latest' # 최신 버전
          extended: true # extended 버전으로

      - name: Build # step 이름 설정
        run: hugo -t hugo-theme-stack # build 명령

hugo를 최신 extended 버전으로 설치하고, build 합니다.

1
2
3
4
5
6
7
8
      - name: Deploy # step 이름 설정
        uses: peaceiris/actions-gh-pages@v3 # github actions 배포 오픈 소스
        with:
          deploy_key: ${{ secrets.DEPLOY_KEY }} # deploy key
          external_repository: cse0518/cse0518.github.io # 배포할 repository 위치
          publish_branch: main # 어떤 브랜치에 올릴지 설정
          publish_dir: ./public # 어떤 경로의 파일들을 배포할지 설정
          commit_message: ${{ github.event.inputs.commitMessage }} # 커밋 메세지 설정

이제 배포를 진행합니다.
아까 생성한 deploy_key를 secrets에 등록했기 때문에
${{ secrets.DEPLOY_KEY }}를 입력하면 설정한 값이 자동 입력됩니다.

public 폴더 안에 있는 파일들을 github.io repository의 main 브랜치에 올립니다.
커밋 메세지를 입력받도록 설정했고, 입력 값을 커밋 메세지로 사용합니다.

자동 배포 실행

혹시 hugo-theme-stack 테마의 exampleSite를 그대로 사용하시는 분들은
먼저 content/post 폴더에 있는 rich-content 폴더를 삭제해주세요.
이 게시글은 빌드가 안되는 내용이 포함되어 있습니다.

이제 blog repository에 push하고 workflow를 실행시켜봅시다!

해당 workflow로 자동 배포를 완료했습니다.

blog repository에서 자유롭게 글을 작성하다가
글 작성이 완료되었을때 배포 workflow를 실행해주면 빠르게 배포가 가능합니다!

혹시 안되는 점이 있다면 댓글을 달아주세요!
최대한 빠르게 답변드리겠습니다.

Hugo 블로그 자동 배포하기

Hugo 블로그(Github.io) Github Actions로 자동 배포하기