Deploying a Github Page Site

Goals

• Automatically deploy the github page site when code is pushed.
• Use a custom domain name (not the {username}.github.io domain, where username is your GitHub account name).
• Use CDN to accelerate resources and improve user access speed.

Implementation

Automatic GitHub Page Deployment

For github page deployment, GitHub provides two solutions:

1. Using custom build workflow (workflow) for building Github Actions

   Vitepress officially provides a way to deploy github page using Github Actions. Click View Details for more information. Add a yaml module (.github/workflows/deploy.yml) in the project root directory:

   name: Deploy
    on:
    workflow_dispatch: {}
    push:
        branches:
        - main
    jobs:
    deploy:
        runs-on: ubuntu-latest
        permissions:
        contents: read
        pages: write
        id-token: write
        environment:
        name: github-pages
        url: ${{ steps.deployment.outputs.page_url }}
        steps:
        - uses: actions/checkout@v3
            with:
            fetch-depth: 0
        - uses: actions/setup-node@v3
            with:
            node-version: 16
            cache: npm
        - run: npm ci
        - name: Build
            run: npm run docs:build
        - uses: actions/configure-pages@v2
        - uses: actions/upload-pages-artifact@v1
            with:
            path: docs/.vitepress/dist
        - name: Deploy
            id: deployment
            uses: actions/deploy-pages@v1

   Note the following in the above yaml module: line 6 (executes GitHub workflow when local code is pushed to the main branch), line 27 (GitHub workflow executes the npm run docs:build script to build the repository), and line 31 (publishes the built artifacts from path: docs/.vitepress/dist). These can be modified according to your project's needs. The current project's modified configuration module is as follows:

   name: Deploy
   on:
   workflow_dispatch: {}
   push:
       branches:
       - main // [!code --]
       - master // [!code ++]
   jobs:
   deploy:
       runs-on: ubuntu-latest
       permissions:
       pages: write
       id-token: write
       environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
       steps:
       - name: Checkout
           uses: actions/checkout@v3
       - name: Install pnpm
           uses: pnpm/action-setup@v2 // [!code ++]
           with: 
           version: 7 // [!code ++]
       - name: Setup node
           uses: actions/setup-node@v3
           with:
           node-version: 16
           cache: 'pnpm'
       - name: Install dependencies
           run: pnpm install --frozen-lockfile // [!code ++]
       - name: Build
           run: npm run docs:build // [!code --]
           run: pnpm build // [!code ++]
       - uses: actions/configure-pages@v2
       - uses: actions/upload-pages-artifact@v1
           with:
           path: docs/.vitepress/dist // [!code --]
           path: .vitepress/dist // [!code ++]
       - name: Deploy
           id: deployment
           uses: actions/deploy-pages@v1

   Since pnpm has fast dependency installation speed and efficient disk space utilization, we use pnpm as the package manager in workflows. Note that the pnpm package manager is not pre-installed in the GitHub Actions runner image (unlike npm and yarn). Therefore, the workspace needs to include pnpm/action-setup to install pnpm. The --frozen-lockfile mode is used for installing dependencies, so the pnpm version used in workflows needs to match the version used when generating pnpm-lock.yaml (in this project, it's v7.0). Also note that

   - name: Install pnpm
       uses: pnpm/action-setup@v2
       with:
           version: latest

   The latest version of pnpm corresponds to pnpm 8.0.0.

   So the project's workflows is quite clear. Every time code is pushed to the master branch, the GitHub workflow will automatically execute, installing pnpm version 7.0, determining the node version (v16), installing project dependencies, and then executing the pnpm build command to build the current repository. The successfully built artifacts from the path .vitepress/dist will be uploaded and automatically deployed to the github page site, which can then be accessed through the {username}.github.io static page.

2. Automatic deployment through branches

Custom Domain Configuration

1. Purchase the desired custom domain through Tencent Cloud (using vrite.cn as an example).

2. Go to DNS Resolution DNSPod to add resolution records for the vrite.cn domain.

3. Add a CNAME record (recommended) or 4 A records in the domain resolution.

   • CNAME record information:

   Host Record	Record Type	Record Value
   www	CNAME	xisenao.github.io

   • A record information:

   Host Record	Record Type	Record Value
   www	A	185.199.108.153
   www	A	185.199.109.153
   www	A	185.199.110.153
   www	A	185.199.111.153

4. GitHub Domain Binding

   In the current deployment repository's Settings -> Pages -> Custom domain, fill in the configured custom domain (www.vrite.cn). Check the Enforce HTTPS option below (After May 1, 2018, GitHub Pages has started providing free HTTPS functionality for custom domains, and has greatly simplified the operation process. Users no longer need to provide their own certificates, they just need to point their domain to their GitHub Pages domain using CNAME.).

At this point, you can access the github page site through https://www.vrite.cn.

CDN Acceleration

Configuration Principle

The original access path was domain -> DNS server -> Github server. Now we add a layer of CDN server to connect the entire process, so the access path becomes domain -> DNS server -> CDN server -> Github server. To implement such a chain, we need to establish the mapping relationship between DNS server -> CDN server and CDN server -> Github server. We also need to enable the CDN server.

Using Tencent Cloud as an example:

1. Enable CDN server

   Add an accelerated domain in Domain Management

   

   Worth mentioning

   1. The added domain needs to be verified. Tencent provides two methods to confirm domain ownership: TXT Record DNS Resolution Verification and File Verification.
   2. Domains with acceleration regions outside China (users accessing from outside China, including Hong Kong, Macau, Taiwan, etc.) do not require ICP filing. However, domains with acceleration regions as Mainland China (users accessing from within China) or Global (users accessing from both within and outside China) require ICP filing.
   3. When accessing a single domain, you need to accelerate both www.vrite.cn and vrite.cn domains, meaning you need to configure twice. This is because when accessing vrite.cn, github will automatically redirect to www.vrite.cn, and the certificate configured on vrite.cn cannot be used on the www.vrite.cn subdomain. Therefore, if you only configure the certificate for vrite.cn, accessing www.vrite.cn will show that the site certificate is invalid.

2. CDN server -> Github server configuration

   Fill in the origin server information (server address to be accelerated) as follows

   

   After configuring the cdn, you will get the cname address provided by the cdn

   

3. DNS server -> CDN server configuration

Add a CNAME record in the domain's DNSPod, other records can be deleted.

Configure certificates for vrite.cn and www.vrite.cn

Tencent Cloud can apply for 50 free certificates. The domain verification method in the certificate application defaults to Automatic DNS Verification, but during this application process, it was found that the automatic addition of CNAME records in DNSPod kept failing verification, and it was later approved by manual customer service (reason not disclosed). For future applications, consider the other two verification methods: Manual DNS Verification and File Verification. The certificate can be approved within 24 hours, after which you can add certificates for both domains.

After configuration, the site should be accessible normally after a while.

WARNING

Found an issue: when the CDN is in arrears, the certificate will also become invalid. Therefore, after payment, you can click the Update button on the right to reset the certificate.

Contributors

XiSenao SenaoXi

Changelog

Last edited 5 months ago

View full history

3bb29bb-feat: i18n

07b83eb-feat: reorganize document directory & change toolbox item to material item

c825862-doc(others-esbuild): esbuild transpiles commonjs behavior

a989f82-chore: format code

eaafd87-chore: reformatting global code

548e2cc-chore: adjust project structure && optimize sidebar

cf57b03-chore: eslint code

3c1841d-chore: supplementary considerations for github workflows

043bb7b-chore: add deploy github page site && add package manager && supplement legacy plugin

c0b47ba-chore: update config & add deploy-github-page-site article & delete unused pictures