Automated CI Workflows in rohitg00/ai-engineering-from-scratch: curriculum.yml and build-book.yml

The rohitg00/ai-engineering-from-scratch repository configures two automated CI workflows—curriculum.yml for lesson validation and site generation, and build-book.yml for EPUB/PDF artifact creation—that run on every push, pull request, and release tag.

The rohitg00/ai-engineering-from-scratch project relies on GitHub Actions to maintain curriculum integrity and publish book artifacts automatically. These automated CI workflows in the .github/workflows/ directory handle everything from lesson auditing to multi-format document generation. Understanding these pipelines reveals how the repository ensures consistent lesson metadata and delivers downloadable book volumes without manual intervention.

Overview of the CI Workflow Architecture

The repository maintains two distinct YAML configurations under .github/workflows/:

• curriculum.yml: Validates lesson structure, enforces naming conventions, and auto-generates site data on every push and pull request.
• build-book.yml: Installs publishing toolchains and builds distributable EPUB and PDF files when commits land on main or when release tags are pushed.

Both workflows execute on the Ubuntu-latest runner and invoke Python and Node.js scripts stored within the repository.

curriculum.yml: Curriculum Validation and Auto-Fix

This workflow acts as the repository's quality gatekeeper, running continuous integration checks that validate content structure and automatically synchronize generated files.

Triggers and Execution Context

The workflow fires on two events:

• push to any branch
• pull_request opening or updating

This ensures that every proposed change undergoes validation before merging.

Lesson Auditing with scripts/audit_lessons.py

The audit job executes scripts/audit_lessons.py to verify lesson-level constraints. The script checks file naming conventions, front-matter validity, and test file presence.

- name: run scripts/audit_lessons.py
  run: python3 scripts/audit_lessons.py

README.md Synchronization

When running on the main branch, the workflow generates a temporary catalog and rewrites lesson counts in README.md. If counts drift, the workflow auto-commits the correction using standard git commands within the Action.

On pull requests, the workflow instead reports a warning if README.md counts are out of sync, allowing maintainers to address discrepancies without automatic commits to feature branches.

Static Site Regeneration

The pipeline also rebuilds site/data.js using site/build.js to keep the static site catalog current:

- name: rebuild site/data.js
  run: node site/build.js

On the main branch, the updated data.js commits automatically; on PRs, the workflow verifies the build succeeds without committing changes.

build-book.yml: Multi-Format Book Generation

This workflow handles the release engineering pipeline, transforming source material into distributable e-book formats.

Toolchain Installation

The job begins by installing pandoc, the Mermaid CLI, and XeLaTeX via system package managers:

- name: Install pandoc
  run: sudo apt-get update && sudo apt-get install -y pandoc

EPUB and PDF Build Process

The workflow invokes scripts/build_book.py to render Markdown and LaTeX sources into EPUB volumes, then leverages pandoc with XeLaTeX for PDF generation. The build executes in discrete steps:

1. Generate EPUB files via the Python build script.
2. Compile PDF volumes using pandoc --pdf-engine=xelatex.
3. Place outputs in outputs/book/ for artifact collection.

Artifact Publishing

Generated files upload to GitHub's artifact storage using actions/upload-artifact@v3:

- name: Upload EPUBs
  uses: actions/upload-artifact@v3
  with:
    name: book-epub
    path: outputs/book/*.epub

When the workflow triggers via a release tag, these artifacts attach automatically to the GitHub release page, providing downloadable EPUB and PDF volumes alongside source code archives.

Key Implementation Files

Understanding the relationship between workflow definitions and their supporting scripts clarifies the automation chain:

File	Location	Purpose
curriculum.yml	.github/workflows/curriculum.yml	Orchestrates validation and auto-fix jobs
build-book.yml	.github/workflows/build-book.yml	Manages book generation and artifact publishing
audit_lessons.py	scripts/audit_lessons.py	Validates lesson structure and metadata
build.js	site/build.js	Generates the static site data catalog
build_book.py	scripts/build_book.py	Converts source material to EPUB/PDF

Summary

• The repository defines two automated CI workflows under .github/workflows/: curriculum.yml for content validation and build-book.yml for publication artifacts.
• curriculum.yml runs on every push and PR, executing scripts/audit_lessons.py to enforce lesson standards while auto-regenerating README.md counts and site/data.js on the main branch.
• build-book.yml triggers on main branch pushes, release tags, or manual dispatch, installing pandoc, Mermaid, and XeLaTeX to build EPUB and PDF volumes via scripts/build_book.py.
• Both workflows use the Ubuntu-latest runner and require no repository secrets, relying solely on version-controlled scripts for their operations.

Frequently Asked Questions

What triggers the automated CI workflows in this repository?

The curriculum.yml workflow triggers on every push to any branch and on pull_request events, ensuring continuous validation of curriculum changes. The build-book.yml workflow activates on pushes to the main branch or release tags, and can also be triggered manually via workflow_dispatch for on-demand book generation.

How does curriculum.yml keep README.md synchronized?

On the main branch, the workflow generates a temporary catalog and rewrites lesson counts in README.md. If the generated content differs from the current file, the workflow commits and pushes the auto-fixed version directly to the repository. On pull requests, it reports drift warnings without pushing changes.

What tools are required to build the EPUB and PDF books?

The build-book.yml workflow installs pandoc for document conversion, the Mermaid CLI for diagram rendering, and XeLaTeX for PDF typesetting. These dependencies install fresh on every workflow run via apt-get and npm, ensuring reproducible builds without relying on pre-configured runner images.

Do these workflows require any secrets or credentials?

No. Both workflows operate without accessing repository secrets. They rely entirely on scripts present in the repository, such as scripts/audit_lessons.py and site/build.js, and use the default GITHUB_TOKEN for artifact uploads and auto-commits.

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