跳至主要内容

技術部落格初體驗：GitHub Action自動佈版GitHub Pages也太方便了吧！？

· 閱讀時間約 7 分鐘
Chao-En Huang
Chao-En Huang
Back End Engineer

每一次都要重新編譯，再 push 到 github 上面好麻煩，而且改一次程式碼就要 push 兩次，也太辛苦了！還好有GitHub Pages和GitHub Actions幫我們完成這些繁瑣的事情，一個 commit，自動部屬到公開的 github pages 真方便~

為什麼要分兩個 repository？​

網站原始碼和公開的部落格分不同的 repository，因為原始碼中可能有一些套件只用於開發，也不需要再公開的部落格用到。另外有些資訊也想要隱藏，分成兩個 repository 能最小限度的公開，另一個能夠設定為 private，就不用擔心內容外流。

本地執行​

在本地端確認能夠執行，說起來很正常，但常常忘了這步，再 github action 編譯不過，才發現本地端根本也編譯不過，雖然很基本但很重要喔！

  1. 在本地端執行網站，可以透過 localhost:3000 查看網站
yarn run start
  1. 在本地端執行編譯，要看到 SUCCESS
yarn build
yarn run v1.22.22
$ docusaurus build
[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.
Done in 58.78s.

設定.gitignore​

在 gitignore 中增加/build，能夠避免編譯好的東西，push 到原始的 repository

.gitignore
# Production
/build

建立流程​

建立一個 private 的 repository 用來儲存網站原始碼​

  1. 建立一個 private 的 repository，這裡要儲存網站的原始碼，填寫任意的Repository Name，並選擇 Private 才能保護原始碼不被任何其他任看見

private_repository_create

  1. 建立一對 rsa 的 key
ssh-keygen -f ./deploy-key -t rsa -b 4096

---

Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ./deploy-key
Your public key has been saved in ./deploy-key.pub
  1. 建立 deploy key，讓 private 的 repository 可以發佈到 public 的 repository

private_repository_create_deploy_key_1

  1. 將剛剛建立 rsa 的 private key(deploy-key)內容貼到 Secret 中，並將 Name 設定為 DEPLOY_KEY

private_repository_create_deploy_key_2

  1. 確認增加成功

private_repository_create_deploy_key_success

建立一個 public 的 repository 用來儲存公開原始碼​

  1. 建立 GitHub Page，需要在 repository name 上輸入，使用者名稱.github.io(例如：koteruon.github.io)，其他地方不要動，不然會失敗，按下 create repository 即可

public_repository_create

  1. default branch 一定要維持是 main，如果是就不用改動

public_repository_setting_overview

  1. 在 setting 中增加 deploy keys，讓 pulbic 的 repository 可以跟 private 的 repository 做認證

public_repository_create_deploy_key_1

  1. 將剛剛建立 rsa 的 public key(deploy-key.pub)內容貼到 Key 中，並將 Title 設定為 DEPLOY_PUB，並且要勾選Allow write access

public_repository_create_deploy_key_2

  1. 確認增加成功

public_repository_create_deploy_key_success

設定 docusaurus.config.ts 上傳到 public repository​

  1. 因為要讓 private repository 的 github action，透過 docusaurus 上傳 public repository，所以這邊是設定成 public repository
./docusaurus.config.ts
const config: Config = {
  url: 'https://koteruon.github.io',
  baseUrl: '/',
  organizationName: 'koteruon', // Usually your GitHub org/user name.
  projectName: 'koteruon.github.io', // Usually your repo name.
  deploymentBranch: 'main', // 很重要，一定要是main
};
export default config;

設定 private 的 repository 的 GitHub Action​

  1. 在 private repository 中，撰寫 GitHub actions，首先點選 Actions，在點選 set up a workflow yourself

private_repository_action_create

  1. 在編輯器裡面填入以下內容，記得修改 user.email 和 user.name 的 XXX 為自己的資訊

private_repository_action_script

.github/workflows/main.yaml
name: Deploy to GitHub Page
on:
  push:
    branches:
      - master
env:
  TZ: 'Asia/Taipei'
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: yarn
      - uses: webfactory/ssh-agent@v0.5.0
        with:
          ssh-private-key: ${{ secrets.DEPLOY_KEY }}
      - name: Deploy to GitHub Pages
        env:
          USE_SSH: true
        run: |
          git config --global user.email "XXX@gmail.com"
          git config --global user.name "XXX"
          yarn install --

以上的內容說明：

  • 在 private repository push branch master 觸發這個 script
  • permissions 允許可以 write
  • 首先第一步驟會 checkout 到 branch 最新的 commit 上
  • 第二步驟是使用 node v22 來編譯
  • 第三步驟是設定好 private key 供等一下上傳到 public repository 用
  • 第四步驟是透過 SSH 連線到 public repository，並且上傳 yarn build 好的內容，這邊通過docusaurus.config.ts中設定的進行部屬到 public repository

自動生成 pulbic 的 repository 的 github action​

  1. 在 public repository 中，GitHub Actions 會自動生成，可以先測試下面一步，理論上會自動生成

public_repository_action_autocreate

測試流程​

驗證上傳 commit 後自動佈版​

  1. 首先上傳原始程式碼到 private repository 的 master branch

testing_private_repository_push

  1. 點選進去可以看到進度，要確認每一個都有打勾，並且左邊是綠色的勾勾，若是紅色則需要查看問題並修正(多半是 yarn build 失敗，透過本地端直接執行也會發現錯誤)

testing_private_repository_action

  1. 再來到public repository，可以看到自動生成一個pages build and deployment的action

testing_public_repository_action

  1. 確認build、report-build-status、deploy都有三個綠色勾勾，就可到https://使用者名稱.github.io查看自己的網站

testing_public_repository_action_success

心得​

之前不小心在public repository，修改到描述、default branch等等，都會造成靜態頁面上傳失敗， 這個時候把整個repository刪除重建就可以了，因此在建立GitHub Pages選項盡量都不要動， 最後看著push到private repository後就能自動在GitHub Pages看到最新內容真的很棒， 我的測試基本上GitHub Pages是即時更新，最多也不超過1分鐘， 所以沒看到更新，基本上就可以到private和public repository的action去找原因囉~