Day 30：Deploy To GitHub Pages

在我们辛苦开发完专案後，需要找一个网路空间，把我们的网站布署上去来提供服务，因此这篇我们将使用Github Pages这个免费的静态网页托管服务，来布署Todolist专案，而布署的过程，将使用Github Actions这个CI/CD服务来进行。

Github Pages

Github Pages是一个免费的网页托管服务，可以将它当作它是一个静态网页的网站服务器，适合放一些简单的宣传网页，或是Demo小专案使用，因为是免费的缘故，所以自然有一些使用上的限制：

1. 仅提供静态页面内容，不包含任何後端程序语言的档案
2. 不能支援如.htaccess之类的密码验证功能，亦即不能针对gh-pages的页面设定密码保护。
3. 所有的Github Pages内容都是公开的，不能设定为Private
4. 档案库大小限制为1GB
5. 每月频宽限100GB
6. 每小时最多能提交10个版本的档案

GitHub Actions

GitHub Actions是一套CI/CD的服务，藉由Action yml档的步骤，可让我们放在GitHub repository中的专案进行建置、测试、布署。透过这个自动化流程，以後将程序码push到master後，就会自动布到Github Pages上了。

接下来开始布署Todolist专案吧到GitHub Pages吧！大致上分为以下步骤：

1. personal access token
2. 撰写yml档
3. 开启GitHub Pages设定

personal access token

peersonal settings / Developer Settings内，左侧选单选择Personal access tokens，输入token名称，另外需要设定repo的权限，这边我们勾选repo，选好後点击Generate Token

接下来页面上有一个绿色区块显示你的token，请将它记下来，因为离开这个页面就再也看不到了。
回到repository的setting，点击左侧选单的secrets，进入後点New secret

将你刚刚记的token写在Value那边，并给这个secret一个名称，这个名称等一下在编辑yml档时会用到，在点Add secret後，就完成了这个步骤

GitHub Actions yml file

在GitHub Actions的布署过程中，这个yml档是最重要的了，里面撰写的内容就是整个建置、布署的详细步骤。

进入repository的Actions页签，可以按set up a workflow yourself，从头开始编辑yml档。下方提供的预设范本则会先写好几个必要步骤，再针对需求加上相关语法进去。

这个范例所准备的yml档完整内容如下：

name: Deploy to GitHub Pages

# 每次程序码Push到master，执行workflow
on:
  push:
    branches: [ master ]

jobs:
  deploy-to-github-pages:
    # 使用ubuntu
    runs-on: ubuntu-latest
    steps:
    # 使用checkout actions
    - uses: actions/checkout@v2
    
    # 安装.NET Core SDK 3.1
    - name: Setup .NET Core SDK
      uses: actions/[email protected]
      with:
        dotnet-version: 3.1    
    
    # 执行单元测试专案
    - name: Run Unit Test 
      run: dotnet test --no-build
      
    # 发布程序到Release资料夹
    - name: Publish .NET Core Project
      run: dotnet publish TodoBlazor/TodoBlazor.csproj -c Release -o release --nologo
    
    # 修改index.html的base href -- 从"/"改为"/TodoBlazor/"
    - name: Change base-tag in index.html from / to TodoBlazor
      run: sed -i 's/<base href="\/" \/>/<base href="\/TodoBlazor\/" \/>/g' release/wwwroot/index.html
    
    # 复制index.html内容到404.html
    - name: copy index.html to 404.html
      run: cp release/wwwroot/index.html release/wwwroot/404.html

    # 加入一个.nojekyll档案
    - name: Add .nojekyll file
      run: touch release/wwwroot/.nojekyll
    
    # 将release/wwwroot的程序码，push到gh-pages分支
    - name: Commit wwwroot to GitHub Pages
      uses: JamesIves/[email protected]
      with:
        GITHUB_TOKEN: ${{ secrets.DeployToken }}
        BRANCH: gh-pages
        FOLDER: release/wwwroot

前几个步骤就是安装.NET Core sdk，再来执行单元测试，发布到Release资料夹，後续几个必要步骤说明如下：

    # 修改index.html的base href -- 从"/"改为"/TodoBlazor/"
    - name: Change base-tag in index.html from / to TodoBlazor
      run: sed -i 's/<base href="\/" \/>/<base href="\/TodoBlazor\/" \/>/g' release/wwwroot/index.html

布署到GitHub Pages後的网址会是 https://{GitHubAccount}.github.io/{RepositoryName} ，而index.html的base href是"/"，意味着Blazor应用程序将会将 https://{GitHubAccount}.github.io/ 当作根目录，将导致应用程序找不到blazor.webassembly.js、css档案等等资源，因此要将base href改为/{RepositoryName}/

# 复制index.html内容到404.html
    - name: copy index.html to 404.html
      run: cp release/wwwroot/index.html release/wwwroot/404.html

这个步骤的用意在於，如果找不到页面的话，将会出现GitHub自己的404页面，但我们想要的效果是出现应用程序自订的404画面，因此我们可以：

1. 在专案的wwwroot底下新增404.html，一旦出现找不到页面的状况，GitHub Pages就会显示这个404.html的内容
2. 第二个方式就是如同yml档中所写的，在每次程序码push到master，执行这个workflow时，会复制index.html内容到404.html到gh-pages这个分支，如果发生找不到页面的状况，会显示Router元件中NotFound template的内容。

  # 加入一个.nojekyll档案
    - name: Add .nojekyll file
      run: touch release/wwwroot/.nojekyll

jekyll是GitHub Pages预设的静态网站产生器，它可以将我们用markdown写好的文章转换成html，但它有一个限制是会排除底线开头的资料夹或档案，这导致_framework资料夹的档案会无法载入，blazor应用程序也执行不起来，好在GitHub Pages是允许我们可以不使用jekyll的，只要加入一个空白档案并命名为.nojekyll即可，加入後就可以顺利载入_framework中的档案

# 将release/wwwroot的程序码，push到gh-pages分支
    - name: Commit wwwroot to GitHub Pages
      uses: JamesIves/[email protected]
      with:
        GITHUB_TOKEN: ${{ secrets.DeployToken }}
        BRANCH: gh-pages
        FOLDER: release/wwwroot

这个步骤是将发布到release/wwwroot底下的静态档案，push到gh-pages分支，这边使用的是GitHub MarketPlace中的github-pages-deploy-action，只要带入3个参数即可：
GITHUB_TOKEN：在上述步骤完成的repo token
BRANCH： 要push过去的分支
FOLDER：此资料夹下的档案将会push到BRANCH设定的分支
顺利执行完这个yml档，就会自动建立好gh-pages分支，并将Todolist的发布档commit过去。

开启GitHub Pages设定

进到repo的setting，往下卷动页面到GitHub Pages，设定分支为gh-pages，然後save，稍待片刻就可以看到已发布完成的讯息。

点进刚刚提供的网址，可以看到我们的Todolist功能正常，完成这次的布署作业

程序码可参考：https://github.com/CircleLin/TodoBlazor