What GitHub CI Workflows Are Used in the cs-self-learning Repository?

The cs-self-learning repository uses a single GitHub Actions workflow to automatically build and deploy its MkDocs documentation site to GitHub Pages on every push to the main branch.

The PKUFlyingPig/cs-self-learning project maintains a comprehensive computer science self-study curriculum. To ensure the documentation website remains synchronized with content changes, the repository implements GitHub workflows for CI that combine continuous integration testing with continuous deployment through a streamlined automation pipeline.

CI/CD Workflow Architecture

The automation pipeline is defined entirely within .github/workflows/ci.yml. This single workflow file orchestrates the complete lifecycle from code checkout to live site deployment using a push-triggered strategy.

Trigger Conditions

The workflow executes on every push event targeting the master or main branches. This configuration ensures that merged pull requests, direct commits, and synchronization events immediately initiate a new documentation build cycle without manual intervention.

Runner Environment

The deploy job runs on an ubuntu-latest runner, providing a standardized Linux environment with preinstalled Git and Python support. This guarantees consistent build behavior regardless of the contributor's local development environment.

Step-by-Step Execution

The deploy job consists of four sequential steps that execute the build and deployment process:

1. Repository checkout using actions/checkout@v2 with fetch-depth: 0 to retrieve the complete Git history
2. Python environment setup via actions/setup-python@v2 configured for the latest Python 3.x release
3. Dependency installation by running pip3 install -U -r requirements.txt to install MkDocs and theme packages
4. Site generation and deployment using the command mkdocs gh-deploy --force to build the static site and publish to GitHub Pages

Key Configuration Files

Three critical files support the CI/CD pipeline and define the documentation build behavior.

Workflow Definition (.github/workflows/ci.yml)

The workflow file defines the deploy job and its execution environment. Below is the complete implementation as found in the repository:

name: ci

on:
  push:
    branches:
      - master
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v2
        with:
          python-version: 3.x

      - run: pip3 install -U -r requirements.txt
      - run: mkdocs gh-deploy --force

Python Dependencies (requirements.txt)

The requirements.txt file pins the exact versions of the static site generator and theme extensions required for reproducible builds:

mkdocs==1.6.0
mkdocs-material==9.5.15

Site Configuration (mkdocs.yml)

The mkdocs.yml file configures the static site generator, specifying the Material theme, navigation structure, and repository metadata. A simplified configuration appears below:

site_name: CS Self-Learning
repo_url: https://github.com/PKUFlyingPig/cs-self-learning
theme:
  name: material
nav:
  - Home: index.md
  - 软件工程: 软件工程/CS169.md
  - 数学进阶: 数学进阶/numerical.md

Deployment Mechanism

The mkdocs gh-deploy --force command builds the static HTML content into the .site/ directory and force-pushes the generated files to the gh-pages branch. GitHub Pages automatically serves content from this branch, making the updated documentation immediately available at the project's public URL. The --force flag ensures the branch history is overwritten cleanly, preventing accumulation of obsolete build artifacts and ensuring the live site mirrors the latest documentation exactly.

Summary

• The cs-self-learning repository uses a single GitHub Actions workflow defined in .github/workflows/ci.yml for continuous integration and deployment.
• The workflow triggers on pushes to master or main branches and executes on an ubuntu-latest runner.
• The pipeline relies on MkDocs with the Material theme, installing exact versions from requirements.txt.
• Complete Git history is fetched (fetch-depth: 0) to support MkDocs plugins that rely on Git metadata for features like revision dates.
• Deployment uses mkdocs gh-deploy --force to atomically update the gh-pages branch and instantly publish changes to GitHub Pages.

Frequently Asked Questions

What event triggers the CI workflow in cs-self-learning?

The workflow triggers on every push event to the master or main branches. This push-based automation ensures that merged pull requests and direct commits immediately initiate a new documentation build and deployment cycle without requiring manual workflow dispatch.

Why does the checkout step use fetch-depth: 0?

The fetch-depth: 0 parameter retrieves the complete Git history rather than a shallow clone. MkDocs plugins and themes often use Git metadata to display page revision dates, last edited authors, and changelog information, requiring access to the full commit history to calculate these values correctly.

Which Python packages are required to build the documentation?

The build requires mkdocs and mkdocs-material as specified in requirements.txt. These packages provide the core static site generator functionality and the Material Design theme used for the documentation interface, ensuring consistent rendering across builds.

How does the workflow deploy to GitHub Pages?

The mkdocs gh-deploy --force command builds the static HTML site into a temporary directory and force-pushes the contents to the gh-pages branch. GitHub Pages automatically serves the content from this branch, and the --force flag ensures the deployment replaces any existing content atomically, maintaining a clean single-commit history on the deployment branch.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}