Skip to content
Hagicode Docs
Blog

HagiCode Practice: How to Use GitHub Actions for Docusaurus Auto-Deployment

Edit page
HagiCode for Windows Microsoft Store artwork
HagiCode for Windows is now on Microsoft Store
HagiCode for Windows is officially live on Microsoft Store. Windows users can install it directly from the storefront and stay on the store-managed update path. Open the listing and take a look.
Open Microsoft Store

Adding GitHub Pages Auto-Deployment Support to HagiCode

This project was originally codenamed PCode and has now been officially renamed HagiCode. This article documents how we introduced automated static site deployment so publishing content becomes as easy as drinking water.

Background / Introduction

During HagiCode development, we ran into a very practical problem: as our documentation and proposals kept growing, efficiently managing and presenting that content became increasingly urgent. We decided to use GitHub Pages to host our static site, but building and deploying it manually was just too cumbersome. Every change required a local build, packaging, and then a manual push to the gh-pages branch. That was not only inefficient, but also easy to get wrong.

To solve this problem, mainly because we wanted to save ourselves some effort, we needed an automated deployment workflow. This article records in detail how we added GitHub Actions-based auto-deployment support to the HagiCode project, so we can stay focused on writing content and let automation handle the rest.

About HagiCode

Hey, let us introduce what we are building

We are building HagiCode — an AI-powered coding assistant that makes development smarter, easier, and more enjoyable.

Smarter — AI assists throughout the entire journey, from idea to code, multiplying development efficiency. Easier — Multi-threaded concurrent operations make full use of resources and keep the development workflow smooth. More enjoyable — Gamification and an achievement system make coding less tedious and more rewarding.

The project is iterating quickly. If you are interested in technical writing, knowledge management, or AI-assisted development, welcome to check us out on GitHub~

Goal Analysis

Before jumping into implementation, we first need to clarify what this task is actually supposed to accomplish. After all, sharpening the axe does not delay the chopping of firewood.

Core Requirements

  1. Automated build: Automatically trigger the build workflow when code is pushed to the main branch.
  2. Automated deployment: After a successful build, automatically deploy the generated static files to GitHub Pages.
  3. Environment consistency: Make sure the CI environment matches the local build environment to avoid the classic embarrassment of “it works locally, but fails online.”

Technical Choice

Since HagiCode is built on Docusaurus, a very popular React static site generator, we can use GitHub Actions to achieve this goal.

Configuring the GitHub Actions Workflow

GitHub Actions is the CI/CD service provided by GitHub. By defining workflow files in YAML format inside the repository, we can customize all kinds of automation tasks.

Creating the Workflow File

We need to create a new configuration file in the .github/workflows directory at the project root, for example deploy.yml. If the directory does not exist yet, create it first.

The core logic of this configuration file is as follows:

  1. Trigger condition: Listen for push events on the main branch.
  2. Runtime environment: The latest Ubuntu release.
  3. Build steps:
    • Check out the code
    • Install Node.js
    • Install dependencies (npm install)
    • Build the static files (npm run build)
  4. Deployment step: Use the official action-gh-pages action to push the build output to the gh-pages branch.

Key Configuration Code

Below is the configuration template we ultimately adopted:

name: Deploy to GitHub Pages


# Trigger condition: run when code is pushed to the main branch
on:
  push:
    branches:
      - main
    # Add path filters if needed, for example only build when docs change
    # paths:
    #   - 'docs/**'
    #   - 'package.json'


# Set permissions, which is important for GitHub Pages deployment
permissions:
  contents: read
  pages: write
  id-token: write


# Concurrency control: cancel older builds for the same branch
concurrency:
  group: "pages"
  cancel-in-progress: false


jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        # Note: fetch-depth: 0 is required, otherwise the build version may be inaccurate
        with:
          fetch-depth: 0


      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20 # Keep this consistent with the local development environment
          cache: 'npm'     # Enabling cache can speed up the build process


      - name: Install dependencies
        run: npm ci
        # Use npm ci instead of npm install because it is faster and stricter, which makes it better for CI


      - name: Build website
        run: npm run build
        env:
          # Configure environment variables here if your site build requires them
          # NODE_ENV: production
          # PUBLIC_URL: /your-repo-name


      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./build # Default Docusaurus output directory


  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Common Pitfalls During Implementation

In practice, we ran into several issues. I am sharing them here in the hope that others can avoid them, or at least prepare solutions in advance.

1. GitHub Token Permission Issues

When we first set things up, deployment kept failing with a 403 (Forbidden). After a lot of digging, we found that GitHub’s default GITHUB_TOKEN did not have permission to write to Pages.

Solution: In the repository’s Settings -> Actions -> General -> Workflow permissions, make sure to select “Read and write permissions”.

2. Wrong Build Directory Path

Docusaurus places built static files in the build directory by default. However, some projects may be configured differently. For example, Create React App defaults to build, while Vite defaults to dist. If Actions reports that it cannot find the output files, check the output path in docusaurus.config.js.

3. Subpath Issues

If your repository is not a user homepage, meaning it is not username.github.io, but instead a project page such as username.github.io/project-name, then you need to configure baseUrl.

In docusaurus.config.js:

module.exports = {
  // ...
  url: 'https://www.hagicode.com', // Your Hagicode URL
  baseUrl: '/', // Deploy from the root path
  // ...
};

This detail is easy to overlook. If it is configured incorrectly, the page may load as a blank screen because the asset paths cannot be resolved.

Verifying the Result

After configuring everything and pushing the code, we can head to the Actions tab of the GitHub repository and watch the show.

You will see a yellow circle while the workflow is running, and once it turns green, it means success. If it turns red, click in and inspect the logs. In most cases, you can track the issue down there, usually a typo or an incorrect path configuration.

Once the build succeeds, visit https://<your-username>.github.io/<repository-name>/ and you will see the freshly deployed site.

Summary

By introducing GitHub Actions, we successfully automated deployment for the HagiCode documentation site. This not only saves the time previously spent on manual operations, but more importantly standardizes the release workflow. Now, no matter which team member updates the documentation, once the change is merged into main, the latest content will be live a few minutes later.

Core benefits:

  • Higher efficiency: We moved from “manual packaging and manual upload” to “code equals release.”
  • Fewer mistakes: We eliminated the possibility of human error during manual operations.
  • Better developer experience: Developers can focus more on content quality instead of being distracted by tedious deployment steps.

Although configuring CI/CD is a bit troublesome at first, especially with all the permissions and path details, it is a one-time investment with major long-term returns. I strongly recommend that every static site project adopt a similar automated workflow.

References

Engagement Prompt

Thank you for reading. If you found this article useful, click the like button below so more people can discover it.

AI Assistance Statement

This content was created with AI-assisted collaboration, reviewed by the author, and reflects the author’s own views and position.

Metadata

Tags:
相关链接
HagiCode for Windows Microsoft Store artwork
HagiCode for Windows is now on Microsoft Store
HagiCode for Windows is officially live on Microsoft Store. Windows users can install it directly from the storefront and stay on the store-managed update path. Open the listing and take a look.
Open Microsoft Store

开始使用 HagiCode

一次安装，几分钟上手

HagiCode for Windows 在 Microsoft Store 免费提供。打开商店即可安装并保持更新；也可以先对比各版本与定价，再决定从哪个渠道开始。

前往 Microsoft Store 安装 查看版本与定价