Intro

갑자기 직접 호스팅하는 블로그를 쓰고싶어져서 깃헙 페이지에 휴고로 만든 사이트를 올려놨다. 하는 김에 휴고 공식 문서를 참고해 깃헙 액션을 통한 자동 배포 설정도 추가하고. 근데 이 문서의 예제대로만 하면 깃헙 페이지 저장소에 단순히 프론트에 노출되는 파일 뿐 아니라 휴고 사이트 설정 파일이나 커스텀 레이아웃 파일 등도 포함되어야 한다. 물론 엄청나게 민감한 정보를 포함되지는 않지만 그래도 좀 찝찝하다. (완전히 동일한 비유는 아니지만) 저장소에 백/프론트가 함께 올라가있고, 거기에 누구나 접근할 수 있는 느낌이랄까?

Github Pages Repository 라고 쓰여있는 모서리가 둥근 사각형 안에 각각 Site Code라고 써있는 원과 Generated Code라고 써있는 원이 들어있는 모양
이렇게 다 들고 있을 필요가 있냐 이 말이지

기존 배포 코드 알아보기

name: GitHub Pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

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

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

위 코드는 깃헙 액션 마켓플레이스에 있는 Hugo setup에 올라와있는 예시 코드이다. 이것들을 다 설명할 필요는 없고, 쭉쭉쭉쭉 내려와서 jobs > deploy > steps 아래 중에 Setup Hugo부터 보자.

Setup Hugo

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

일단 얘는 peaceiris/actions-hugo@v2를 사용한다. 이거는 현재 액션을 수행하는 머신에 휴고 환경을 만들어주는 액션이다. 여기서는 보시다시피 사용할 휴고 버전을 명시할 수 있다. 본인이 원하는 대로 설정하자. 휴고 모듈을 캐싱한다던가, 저장소 내에 환경변수를 지정해 휴고 버전을 지정한다던가 하는 것은 굳이 여기서 얘기하지 않겠다. 위에서 링크를 걸어둔 Hugo setup 마켓플레이스 페이지로 가면 다 나와있다.

Build & Deploy

- name: Build
  run: hugo --minify

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  if: ${{ github.ref == 'refs/heads/main' }}
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

휴고 환경설정을 해줬으니 빌드는 간단하다. hugo --minify를 실행해준다. 이 명령어에 대한 설명은 Hugo CLI 문서의 ‘options’ 항목에서 찾을 수 있다. 간단하게

minify any supported output format (HTML, XML etc.)

라고 설명하고 있는데, 말 그대로 사이트 서빙을 위한 최소화된 파일을 생성해준다고 보면 된다.

빌드를 했으니 배포해야겠지? 배포에는 peaceiris/actions-gh-pages를 사용한다. 깃헙 페이지를 위한 액션으로 이 역시 마켓플레이스에서 자세한 내용을 찾을 수 있다. 간단하게 설명하자면 publish_dir에서 지정한 디렉토리의 내용을 지정된 브랜치(기본값은 gh-pages)로 배포하는 것이다. 지금은 휴고 사이트 코드와 생성된 코드가 동일한 저장소에 존재하기 때문에 별도의 설정 없이 단순히 ${{ secrets.GITHUB_TOKEN }}으로 깃헙이 자동 생성해주는 토큰을 사용할 수 있다. 여기까지의 흐름은 다음과 같다(클릭하면 크게 볼 수 있다).

Github Pages 저장소에 코드 변경사항이 생겼을때 Github Actions를 통해 사이트를 생성하고 스스로 배포하는 흐름을 묘사한 그림

하지만 우리의 목적은 이게 아니다. 깃헙 페이지 저장소가 아닌 별도의 저장소에 코드를 푸쉬하면 깃헙 액션 러너가 해당 코드를 기반으로 빌드하고 그 결과물만 깃헙 페이지 저장소에 배포해야 하는 것이다.

사이트 코드 저장소의 깃헙 액션을 통해 페이지 저장소 코드에 배포하기

일단 우리가 원하는 모양새가 무엇인지 명확히 하기 위해 한번 더 도표를 그려보겠다(클릭하면 크게 볼 수 있다).

별도의 블로그 소스 코드 변경사항이 생기면 Github Actions를 통해 사이트를 생성하고 Github Pages 저장소로 배포하는 흐름을 묘사한 그림

차이가 느껴지는가? 별도로 소스 코드를 지니는 private 저장소를 마련해두고, 이 저장소에 코드가 푸쉬되면 액션을 수행하도록 하는 것이다.

Action 수정

이때 전체적인 흐름은 위에서 보여준 yaml 파일과 비슷하지만, Deploy 부분이 약간 다르게 구성된다. 대충 이런 식이다.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  if: github.ref == 'refs/heads/main'
  with:
    deploy_key: ${{ secrets.GH_ACTION_DEPLOY_KEY }}
    external_repository: XXX/XXX.github.io
    publish_branch: main
    publish_dir: ./public

다른 부분은 다 같은데, 세 부분이 다르다. 바로 deploy_key, external_repository, publish_branch다. deploy_key에 대해서는 잠시 미뤄두고, 나머지 두 개를 먼저 살펴보자.

external_repository는 말 그대로 외부 저장소를 말한다. 위의 도표를 보면 알다시피 Github Pages 저장소가 아닌 별도의 소스 코드 저장소에서 실행되는 액션이기 때문에 프론트 코드가 배포될 Github Pages 저장소를 따로 명시해야한다. 이 경우에는 사용자명이 XXX라 치고 값을 써두었다.

publish_branch는 Github Pages의 프론트 코드가 main 브랜치로 배포되도록 지정한 것이다. peaceiris/actions-gh-pages 액션의 기본 설정은 사용자로 하여금 Github Pages 저장소의 main 브랜치가 아닌 별도의 브랜치(gh-pages)에 프론트 코드가 푸쉬되도록 한다. 그러면 이 별도의 브랜치에는 사이트 코드를 제외한 프론트 코드만 남아있어 하나의 저장소에서 두개의 코드를 들고 있는 것처럼 관리할 수 있다. 하지만 우리는 아예 저장소 자체를 분리해버렸기 때문에 브랜치로 소스를 분리할 필요가 없다. 그러니 그냥 main 브랜치로 배포하도록 지정하는 것이다.

deploy_key는 Github Pages 저장소에 생성된 코드를 배포하기 위한 배포키를 적는 곳이다. 그렇다면 왜 갑자기 배포키가 필요한 것일까? 이전 예시에서는 액션을 수행하는 저장소와 코드가 배포될 저장소가 동일한 저장소였기 때문에 자동으로 생성되는 토큰을 사용해도 문제가 없었다. 하지만 지금같은 경우에는 액션이 수행되는 저장소와 코드가 배포될 저장소가 다르기 때문에 자동으로 생성되는 토큰을 사용할 수 없다. 이와 같은 상황에 대비해 Github에서는 저장소별 Deploy Key를 지정하는 기능을 제공한다.

생성된 코드를 배포하기 위한 Deploy Key 적용

Github Docs의 Generating a new SSH Key 문서를 참고해 배포를 위한 SSH 키쌍을 생성한다. 이 때 공개키와 비밀키가 한 쌍 생성되는데, 이걸 배포키로 등록하는 것이다.

Github Pages 저장소의 Deploy Keys 메뉴에서 새 키를 설정하는 화면

Github Pages 저장소의 Settings 탭으로 이동하고 Deploy Key 메뉴로 들어간다. 그리고 오른쪽 위에 있는 ‘Add deploy key’를 눌러 진입한 페이지에서 필요한 내용을 붙여넣는다. 이후 ‘Allow write access’를 체크하고 ‘Add key’ 버튼을 클릭하면 배포 키가 등록된 것이다. 이때 ‘Allow write access’ 를 체크하지 않으면 배포키가 있어봤자 코드 푸쉬를 할 수 없으니 의미가 없다. 꼭 체크해주도록 하자.

Hugo 사이트 코드 저장소의 Secrets 메뉴 아래 Actions 메뉴에서 새 키를 설정하는 화면

이걸로 Github Pages 저장소에 코드 배포를 할 수 있는 배포키의 공개키를 등록하는 작업을 완료했다. 이 공개키는 일종의 전용 출입문으로, 열쇠가 있다면 이 문을 통해 배포 작업을 수행할 수 있다. 그러면 이제는 액션을 수행하는 저장소에다가 출입문 열쇠를 알려줘야겠지? 별도로 마련한 깃헙 액션을 수행하는 휴고 사이트 코드 저장소의 Settings 탭으로 이동하고 Secrects 메뉴 아래 Actions 메뉴에 들어가 오른쪽 위의 ‘New repository secret’ 버튼을 눌러 비밀키 입력 화면을 들어간다. 해당 화면에서 Name에는 Github Actions의 선언파일에서 호출할 Secret의 변수명을 지정한다. 아까 위에서 deploy_key: ${{ secrets.GH_ACTION_DEPLOY_KEY }} 라는 부분이 있었을텐데, 이 GH_ACTION_DEPLOY_KEY가 이에 해당한다. Value에는 비밀키 내용을 빠짐없이 붙여넣는다(Begin 어쩌구 End 어떠구 하는 부분 포함).

이제 액션을 수행할 저장소에게 적절한 열쇠를 쥐여주고, 배포 동작을 할때 어떤 열쇠를 들고가야할지 알려주었으니 뭔가 변경사항을 만든 다음에 코드를 푸쉬해보자. 알아서 배포가 착착 진행되는 것을 확인할 수 있다.