Github Action 自動部署 github-pages

Github pages 適合展示靜態頁面，只要在 github 建立 gh-pages 分支，可依據用戶名稱和repo名稱來開啟頁面。

https://[USER_NAME].github.io/[REPO_NAME]/

以這個專案為例

https://github.com/chenuin/JavaScript30

路徑會是

https://chenuin.github.io/JavaScript30/

使用 JamesIves/github-pages-deploy-action@v4.3.3 有兩個必填參數：

• branch: 分支
• folder: 目錄，.代表整個repo根目錄

參數詳細說明請參考這裡，在 repo 裡新增 github action (連結):

name: Github pages

on:
  # Triggers the workflow on push events but only for the "master" branch
  push:
    branches: master

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v3

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4.3.3
        with:
          branch: gh-pages
          folder: .
          token: ${{ secrets.GH_PAT }}

GH_PAT 設定方式，請先至 Settings => Developer settings => Personal access tokens (或下方連結)，按右上角新增Token，scopes 可直接勾選 repo 並將Token複製。

https://github.com/settings/tokens

再到專案的 Settings => Secrets => Actions (或下方連結)，按右上角新增，命名 GH_PAT 並將剛剛複製的Token貼上。

https://github.com/[USER_NAME]/[REPO_NAME]/settings/secrets/actions

EASY!!

相關文章：

• Github Actions 自動 Jekyll 專案部屬 Github Pages
• [Github] 在github.io建立免費的網站

Github Actions 自動 Jekyll 專案部屬 Github Pages

自從完成「Travis CI 自動 Jekyll 專案部屬 Github Pages 完整範例」很久沒有更新 Github Pages，近期上傳時卻發現CI執行失敗，並不是腳本有問題或編譯過程有錯誤，而是request被拒，所以即使換了Github Token依舊無法解決。

直到我發現 Travis CI 帳戶設定突然多了「Plan」，有免費的方案可以選擇，選擇之後再讓Job重跑居然就成功了，所謂的免費方案是給 10000 available credits，每次執行Job時就會扣點直到用完為止，之後可以一次性購買或者選擇月費方案。

Github Actions 是 Github 內建的功能，可以定義Repo自動化、執行CI/CD相關工作，因此決定將 Travis CI 的功能由 Github Actions 取代，以下將說明如何移除 myblog 原本 .travis.yml 的設定 ，以 Github Actions 自動部屬至 Github Pages。

一、選擇 Workflow 建立方式

方法一：

在專案根目錄

新增目錄 .github/workflow/，並在 workflow/ 新增副檔名為 .yml的檔案。

方法二：

到 Github repo上設定

可更改檔名和底下的內容

二、新增 Workflow

name 命名，可自行決定名稱

name: website

on 必填的設定，Github Action提供各種事件供選擇觸發時機，這邊設定為 push 時執行，也可以針對多個事件指定分支。

# Triggered when code is pushed to any branch in a repository
on: push


# Or ....
on:
  # Trigger the workflow on push,
  # but only for the main branch
  push:
    branches:
      - main

jobs 接下來是最重要的部分，workflow是由一個或多的Job組成，預設情況下會同時執行，每個 Job 必須給一個唯一的 job_id，是由數字、字母或 _、 - 組成的字串，且字首只能由字母或是 _。因此我們第一個發布 - publish 的動作：

jobs:
  publish:

再來是 publish 內需要哪些設定：

runs-on 必填的設定，使用哪種機器執行 workflow，像是 Ubuntu、macOS、windows server等 Github 提供的虛擬環境。

runs-on: ubuntu-latest

steps 定義有哪些任務，Job 由一連串的任務組成，可以替任務命名，會在 Github 上顯示。

uses 指定動作(Action)，通常是一些重複性的執行動作，被打包成一個套件，可以在這裡直接使用，更多相關的套件可以到 Github marketplace 搜尋 。底下使用的是checkout一個新的分支並安裝Ruby。

steps:
  # Reference the major version of a release
  - uses: actions/checkout@v2   # Downloads a prebuilt ruby
  - uses: ruby/setup-ruby@v1

run 在虛擬機器 shell 上執行 command-line

steps:
  - run: bundle install
  - run: chmod +x ./script/cibuild
  - run: ./script/cibuild

with 執行動作時可以加入參數，利用 github-pages 可以快速設定，我們指定將網站部署到 chenuin/chenuin.github.io 這個 repo 的 master 分支，需要上傳的目錄為 ./_site ，也就是Jekyll編譯好的檔案目錄。

steps:
  - uses: crazy-max/ghaction-github-pages@v2
    with:
      repo: chenuin/chenuin.github.io
      target_branch: master
      build_dir: ./_site
    env:
      GITHUB_TOKEN: ${{ secrets.GH_PAT }}

env 這裡分為 GITHUB_TOKEN和GH_PAT兩種，前者不需要任何設定、僅限於同一個 repo 內的操作，後者則是部署到其他 repo 使用的。(說明)

GH_PAT 設定方式，請先至 Settings => Developer settings => Personal access tokens (或下方連結)，按右上角新增Token，scopes 可直接勾選 repo 並將Token複製。

https://github.com/settings/tokens

再到專案的 Settings => Secrets => Actions (或下方連結)，按右上角新增，命名 GH_PAT 並將剛剛複製的Token貼上。

https://github.com/[USER_NAME]/[REPO_NAME]/settings/secrets/actions

關於 GITHUB_TOKEN 可以看這部影片了解更多：

完整檔案如下：

name: website

on: push

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 2.6
      - name: Install dependencies
        run: bundle install
      - name: Before srcipt
        run: chmod +x ./script/cibuild
      - name: Srcipt
        run: ./script/cibuild
      - name: Deploy to GitHub Pages
        if: success()
        uses: crazy-max/ghaction-github-pages@v2
        with:
          repo: chenuin/chenuin.github.io
          target_branch: master
          build_dir: ./_site
        env:
          GITHUB_TOKEN: ${{ secrets.GH_PAT }}

檔案異動內容已經上傳至 Github ，可點選連結查看。

三、查看執行結果

https://github.com/[USER_NAME]/[REPO_NAME]/actions

相關文章：

• [Github] 在github.io建立免費的網站
• 靜態網頁部落格工具 Ruby + Jekyll 安裝教學
• Travis CI 自動 Jekyll 專案部屬 Github Pages 完整範例

參考連結：

• Github Actions 文件
• Ruby 環境安裝預設值及參數說明
• Github pages 預設值及參數說明

Asciidoctor 專案使用 Travis CI 自動部屬程式範例

Asciidoctor可以轉成 HTML 格式，所以可以使用 Travis CI 自動將 progit book 專案上傳到 github pages。

一、新增 .travis.yml

先將專案編譯成 HTML 等，並將相關的檔案放到新建的目錄 /publc 。

script:
  - bundle exec rake book:build
  - mkdir public
  - cp progit.html public/index.html
  - cp progit.{pdf,epub} public/
  - cp -r images/ public/

接著是部屬的部分，目錄 /publc 就是我們要放在網頁上的資料，develop 則是我們目前的分支名稱：

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_API_TOKEN
  local_dir: ./public
  on:
    branch: develop

.travis.yml 完整程式碼請參考[這裡]，或到官網參考更多的設定參數。

二、設定 Github Token

請參考 [這裡] 第二步驟，按照方法在 Travis CI 新增環境變數 GITHUB_API_TOKEN 。

三、更新

Push 到遠端後後，等 2-3 分鐘 CI 完成，Repo會多一個分支 gh-pages ，裡面會有複製過去的首頁、圖片等資料，再到 github.io 打開頁面就能看到成果。 

Github Repo:

https://github.com/chenuin/progit2-zh-tw/ 

Github pages:

https://chenuin.github.io/progit2-zh-tw/ 

https://chenuin.github.io/progit2-zh-tw/progit.pdf

Travis CI 自動 Jekyll 專案部屬 Github Pages 完整範例

了解如何「[Github] 在github.io建立免費的網站」，搭配使用 Jekyll 可以讓部落格或靜態網站的撰寫更加便利，完成內容的更新後，可以透過指令編譯 _site 的目錄，轉成瀏覽器可讀的格式，最後將目錄上傳到web server。

這些流程可以使用 Travis CI 自動化，當 github repo 收到新的 Request時，自動編譯上傳到 github.io。 若未有 Jekyll 專案，請先參考「靜態網頁部落格工具 Ruby + Jekyll 安裝教學」，建立一個新專案。

一、新增編譯腳本

mkdir script
vim script/cibuild

script/cibuild 內容如下(參考檔案):

#!/usr/bin/env bash
set -e # halt script on error

JEKYLL_ENV=production bundle exec jekyll build
# bundle exec htmlproofer ./_site

二、新增 Travis CI 設定檔

.travis.yml 內容如下(參考檔案):

language: ruby
rvm:
- 2.6
script: ./script/cibuild
before_script:
- chmod +x ./script/cibuild
deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  repo: chenuin/chenuin.github.io
  local_dir: ./_site
  target_branch: master
  on:
    branch: master

TOKEN 設定(參考)

1. 開啟頁面 https://github.com/settings/tokens/new
2. 填寫備註(可以自行決定)，並選擇 public_repo
3. 送出

將畫面顯示的 token 複製保存好，到 Travis CI 設定環境變數，新增一個參數 GITHUB_TOKEN，內容就是剛剛複製的這一串字串 。 

※操作畫面可參考「Travis CI 快速部屬 Jekyll + Asciidoctor」的第四步驟 - 新增 github token 。

三、上傳

git add .
git commit -m 'init commit'
git push origin master

專案連結： 

https://github.com/chenuin/myblog 

https://chenuin.github.io/

Travis CI 快速部屬 Jekyll + Asciidoctor

Github.io可以支援markdown，若要 asciidoctor 進行編輯，可以透過 Jeykll 在 github 上提供的專案，免去複雜的設定，快速完成布署。內容是參考 README，作業系統為 Ubuntu，統整成下面的步驟：

一、安裝

靜態網頁部落格工具 Ruby + Jekyll 安裝教學

Asciidoctor 安裝及入門範例

二、下載原始碼

請先 fork jekyll-asciidoc-quickstart ，再下載專案 jekyll-asciidoc-quickstart

git clone https://github.com/[github-account]/jekyll-asciidoc-quickstart

三、設定 Travis CI

Travic CI 先後推出 travis-ci.org、travis-ci.com，兩者的介面很相近，以下都是使用 travis-ci.com 進行操作。

請先到 github settings，將這個專案同步到 Travis CI上。 

 

四、新增 github token

1. 開啟頁面 https://github.com/settings/tokens/new
2. 填寫備註(可以自行決定)，並選擇 public_repo
3. 送出

請將畫面顯示的 token 複製保存好，一旦離開此頁面，就不會再看到這串 token。若遺失 token，只能再另外產生一組新的。

 

完成後，到 Travis CI 設定環境變數(Environment Variables) 

Name:  GH_TOKEN

Value: [token]  (剛剛在github複製的字串)

按下 Add 完成設定。 

 (連結參考 https://travis-ci.com/github/[github-account]/jekyll-asciidoc-quickstart/settings)

  

直接在網頁上新增更方便，原始文件提供的方法是安裝 travis 的套件，用指令加密 token 後，直接新增到 .travis.yml，也可以參考試試看。

五、編輯 .travis.yml

原始專案設定 rvm 版本已經太舊了，請把 2.2 改成 2.6，否則 CI 執行會失敗。

# .travis.yml
rvm:
  - 2.6

完整檔案請看: .travis.yml

git add .travis.yml
git commit -m 'update rvm version'

六、上傳

git push -u origin master

可以到 Travis CI 上確認執行結果，若正確設定的話，將自動把 master 的內容編譯後，自動上傳到分支 gh-pages 。 

開啟頁面 https://[github-account].github.io/jekyll-asciidoc-quickstart/ ，順利看到畫面就完成了。

完整專案範例

https://github.com/chenuin/jekyll-asciidoc-quickstart

https://chenuin.github.io/jekyll-asciidoc-quickstart/ 

[Github] 在github.io建立免費的網站

Github提供免費的方式建立自己的網站，不過只限於靜態的網頁，適合寫個人履歷、部落格或網站作品的分享，設定方法如下：

步驟一、建立Repository

名稱為[USERNAME].github.io，[USERNAME]請填入github的帳戶名稱。

步驟二、新增頁面

用command line方式進行說明

git clone https://github.com/[USERNAME]/[USERNAME].github.io
cd [USERNAME].github.io
vim index.html

內容可以自己決定

<!DOCTYPE html>
<html>
 <head>
  <title>Home</title>
 </head>
 
 <body>
  <h1>Welcome</h1>
  <p>This is my first page.</p>
 </body>
</html>

步驟三、更新

git add index.html
git commit -m "Initial commit"
git push -u origin master

最後打開瀏覽器就可以看到成果囉！

https://[USERNAME].github.io

除了[USERNAME].github.io以外Repository，其他也可以建立一個新的分支(branch)，命名為gh-pages，透過github.io訪問這個專案，同時保持所有的專案維護的方便性。

https://[USERNAME].github.io/[REPO_NAME]

https://pages.github.com/