Hugo 部落格建置 - 透過 Github Action 編譯與部署

本篇文章介紹如何透過 Github Action 使用 Hugo 產生 Blog 頁面(SSG)，並透過 Github Action 部署到 Github 的個人網站上。

前言

會寫這篇，一來是因為有點忘記當初是怎麼架設的，二來是這個 blog 被看到了，對方敲碗詢問怎麼運作的，於是才有了這篇文章。

在看這篇文章之前，請先看Hugo 部落格建置 - 安裝與部署這篇文章，我們先把本地的環境架設好，再開始做後續的事情！

建立 repo

在這之前，我們要先建立兩個 repo，一個請你用你的帳號名稱命名，格式為[username].github.io，我這次的範例是 weiweihugo.github.io，這邊是要存放編譯後所產生的網頁檔。這個 repo 請選擇 public，因為是要給別人看的。

另一個 repo 請你用你自己好記的名稱命名即可，這邊是要存放你的編譯環境，我們之後會把我們在本地端的環境 push 上去。這個 repo 請務必選擇 private，因為會存放 key，避免 key 外流而使得他人可以對你的 repo 動手腳。

建立好了之後，我們先隨意上傳一個 index.html 並設定，確認我們是否能透過 [username].github.io 瀏覽到網頁。這邊的 index.html 就自己先隨意設計一個即可。

如果上傳成功後，你應該能直接透過 [username].github.io 瀏覽到網頁。

建立 workflow

我們進入那個 private 屬性的 repo，直接點選上方的 action，並選擇 Simple workflow。

接著貼上我已經寫好了 workflow，並稍微修改後面的變數即可。我有在內部加上說明。

name: CI
# 當我們 push 時會觸發。
on: push 
jobs:
  deploy:
    # 我們設定 ubuntu 為 runner。
    runs-on: ubuntu-20.04
    steps:
      - name: Git checkout
        uses: actions/checkout@v2
      # 安裝 hugo，這裡使用最常被用的 peaceiris/actions-hugo@v2
      - name: Setup hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.92.2"
      # 這邊是建置時使用的指令，我喜歡用 --minify
      - name: Build
        run: hugo --minify
      # 這邊是部署的部分
        # token 後續會提到，不用動。
        # 要動的只有 external_repository, user_name, user_email
        # 如果你有改網頁產出的目錄，請更動publish_dir
        # 如果你需要更改 target branch，請更改 publish_branch
        # 如果 workflow 不能用的話，可以檢查一下各行的 tag 跟 space。
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.TOKEN }}
          external_repository: username/username.github.io
          publish_dir: ./public
          user_name: 你的username
          user_email: 你的信箱
          publish_branch: main 

這時候，Github action 應該會開始運作，並且給你一個叉叉，因為我們又還沒上傳本地端的環境。

上傳本地端環境

我們須將 config.toml 的那個目錄為相對根目錄，把所有檔案 push 上去到 private 那個 repo，也就是有 workflow 的那個 repo，不要推錯了唷！

這個時候，因為我們又做了一次 push ，所以又會再一次執行 Github Action，此時又給我們一個叉叉，是因為我們沒有設定 token，所以我們接下來要來產生 Token 並設定。

Token

因為我們是跨 repo 進行，故不能使用 repo 內的 secret 功能，我們需要到個人設定內的 developer setting 內進行。

Note 的部分就使用容易識別的，日期的話 github 有限制，最長是一年的樣子。
權限的話只需要開 repo 跟 workflow 即可。

之後我們到 private 這個 repo 設定 token，點選 New repository secrets

接著會有兩個欄位要填寫：

• Name : 如果你稍早的 workflow 是使用 ${{secrets.TOKEN}} ，那這邊就要填入 TOKEN，如果是自己取變數名稱叫做 ${{secrets.XXX}}，那這邊就填入XXX。
• Secret : 貼上剛剛產生的 Token。

  

到這邊就完成囉！你可以到 Github Action 內 re-job 或是 push 上去，讓 Github Action 再讓你重新產生頁面並部署到你的 Github pages 上，接著用[username].github.io 瀏覽網頁。

往後你也只需要 push content 內的內容即可，如果你有做 theme 或是相關的修改，一律 push 就對了！！

參考資料

1. 使用 Github Actions 來自動化部署 Hugo 到 Github Pages
2. Managing your personal access tokens
3. peaceiris/actions-hugo@v2