How to Build and Deploy a Hexo Blog on GitHub Pages with CI/CD

Preface

Ways to Build a Blog

1. Use online blog platforms such as Yuque, Juejin, CSDN, etc.

Advantages: create an account and start immediately, simple, no maintenance.

Disadvantages: articles are scattered across platforms, hard to manage.

2. GitHub Pages + static generators like Hugo, Hexo (highly recommended).

Advantages: all articles are under your control, easy to manage, and you can learn many related technologies while building from scratch.

Disadvantages: only static content, no backend management system.

3. WordPress (not used here).

Advantages: easy backup and migration, powerful extensions, friendly for custom users, built‑in backend management.

Disadvantages: many features make it unfriendly for beginners.

Personal Choice

I chose the second option: github pages + hexo, which lets me learn GitHub Actions, GitHub Pages, GitHub Discussions, and have a personal blog to showcase on my résumé.

Body

How to Set Up

First, create a local Hexo site.

$ npm install hexo-cli -g

$ hexo init blog
$ cd blog
$ npm install

$ hexo server

Visit the local server to see the site.

Add a new article: hexo new <em>post-title</em> The command creates a markdown file under source/_posts where you can write content.

Deploy Hexo to GitHub Pages

Create a repository on GitHub and push the Hexo files to the default branch ( main or master). $ git push -u origin main Ensure public/ is excluded via .gitignore.

Configure GitHub Pages to use GitHub Actions as the source, then add a workflow file .github/workflows/pages.yml:

name: Pages
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          submodules: recursive
      - name: Use Node.js 16.x
        uses: actions/setup-node@v2
        with:
          node-version: '16'
      - name: Cache NPM dependencies
        uses: actions/cache@v2
        with:
          path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      - name: Install Dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./public
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

After the workflow runs, the site is available at the GitHub Pages URL.

Advanced: Theme and Comments

Install a Hexo theme, e.g., Icarus:

$ npm install hexo-theme-icarus
$ hexo config theme icarus

Configure the generated _config.icarus.yml as needed.

For comments, you can use Changyan, Giscus, or Gitalk.

Mirror to Gitee and Deploy Gitee Pages

Add a job to the workflow to mirror the repository to Gitee:

mirroring-gitee:
  needs: [build, deploy]
  runs-on: ubuntu-latest
  steps:
    - name: Use Node.js 16.x
      uses: actions/setup-node@v2
      with:
        node-version: '16'
    - name: Mirror the Github organization repos to Gitee.
      uses: Yikun/hub-mirror-action@master
      with:
        src: 'github/YourGitHubOrg'
        dst: 'gitee/YourGiteeOrg'
        dst_key: ${{ secrets.GITEE_PRIVATE_KEY }}
        dst_token: ${{ secrets.GITEE_TOKEN }}
        static_list: "your-blog-repo"
        force_update: true
        timeout: '5m'

Configure the necessary secrets and SSH keys in both GitHub and Gitee as described.

After the workflow finishes, the site is also available on Gitee Pages, providing faster access in regions where GitHub is slow.

Now you can add new posts with hexo new <em>title</em> and push them to the remote repository.