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

> Discover the GitHub CI workflows in the cs-self-learning repository. Learn how MkDocs documentation is built and deployed automatically to GitHub Pages on each push.

- Repository: [Yinmin Zhong/cs-self-learning](https://github.com/PKUFlyingPig/cs-self-learning)
- Tags: how-to-guide
- Published: 2026-03-02

---

**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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.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:

```yaml
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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/requirements.txt))

The [`requirements.txt`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/requirements.txt) file pins the exact versions of the static site generator and theme extensions required for reproducible builds:

```text
mkdocs==1.6.0
mkdocs-material==9.5.15

```

### Site Configuration ([`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml))

The [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) file configures the static site generator, specifying the Material theme, navigation structure, and repository metadata. A simplified configuration appears below:

```yaml
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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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.