起源於最近想要把之前隨手在 hackmd.io 打的筆記放到 GitHub 上讓朋友共編,先放個最後的成果: WildfootW / Security-Note ,當 main branch 有新的 push 時會自動生成 Daux.io 的 static html 檔,並且 push 到 gh-pages branch。
一開始是打算參考 OneJar 的文章 (免費無限建立自己的 GitBook 圖文教學 – 利用 GitHub Pages + GitHub Actions 自動發佈) 直接照做,但是有幾個問題:
- gitbook 已經遺棄開源社群,把原本的 gitbook 改為 legacy ,另外做了一個毫不相干的服務。
- OneJar 寫的 GitHub Actions 是從頭到尾只有一個步驟,用他自己寫的 Dockerfile,也就是說 push gh-pages 要用到的 token 也要 Pass 給他做的 Docker,身為一個有資安潔癖的人實在有點困擾。
於是才決定改用 Daux.io 來做,順便研究 CI。
我們最主要的結構如下:
- .github/workflows/documentation.yml ─ GitHub Actions 需要的檔案,檔名可自訂。
- docs/chapter…/articles… ─ 文章的目錄和文章本身
- docs/config.json ─ Daux.io 生成書的設定檔,內容相當直覺,可以去 Daux.io 的 repo 看看。
docs 裡面的東西都是 Daux.io 要用的,直接看他的文件就好。
稍微講解下我理解的 GitHub Actions 的運作(但我沒仔細看過文件,有錯請各位指教),GitHub Actions 會在他被觸發的時候有一個環境,可以是 Linux 或 Windows 都有支援,像是我的這個 repo ─ Security-Note
,runs-on 選 ubuntu,他的 $GITHUB_WORKSPACE = /home/runner/work/Security-Note/Security-Note
接下來的 jobs 都會從這邊執行。
接下來解釋下,GitHub Actions 的這個設定檔,幾乎都是從 Daux.io 那邊抄來的,但是 Daux.io 那邊是使用本身自帶的 Daux.io Binary,而我不想在每個 repo 都放一份 Daux.io ,所以那個部分改用 Docker 取代(順帶一提,GitHub Actions 的環境似乎有自帶 Docker)。
name: Documentation
on:
push:
branches: [ main ]
jobs:
documentation:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
persist-credentials: false
- name: Generate documentation
run: docker run --rm -w /build -v $GITHUB_WORKSPACE:/build daux/daux.io daux generate
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@3.7.1
with:
FOLDER: "static"
BRANCH: gh-pages
GITHUB_TOKEN: ${{ secrets.GH_PAGES_TOKEN }}
首先 on 的那個部分很直覺,就是說 push 到 main 的時候會觸發這個 Actions
jobs 裡面分成好幾個步驟:
- checkout@2 把 repo 的內容 clone 進 $GITHUB_WORKSPACE
- 用 daux/daux.io 的 Docker File 生成 HTML 的 static files
- 把 HTML 的 static files push 到 gh-pages branch
另外要說的部份是第三個步驟要 push 回 repo ,所以要去 Settings / Developer settings / Personal access tokens 增加一個 token 包括 public_repo, repo:status,再在 Settings / Actions secrets 增加 GH_PAGES_TOKEN
(符合設定檔裡的名稱)。
基本上把這個設定檔 push 上去 repo 和設定完 Secret 就會動了,但有時候 GitHub Actions 會卡住,可以睡一覺再起來看。