CI/CD Workflow Defined in curriculum.yml: Automating Curriculum Validation and Site Deployment

The curriculum.yml GitHub Actions workflow in the rohitg00/ai-engineering-from-scratch repository orchestrates a four-job pipeline that validates lesson structure, synchronizes documentation, and regenerates the static site on every push and pull request.

The .github/workflows/curriculum.yml file defines the continuous integration and delivery pipeline for the AI Engineering from Scratch curriculum. This workflow ensures that all lessons adhere to strict structural requirements while automatically maintaining the README counts and public website synchronization.

Workflow Triggers and Architecture

Event Triggers

The workflow activates on two primary GitHub events: pushes to the main branch and all pull requests. This dual-trigger strategy ensures that contributions are validated before merging while keeping the production branch's generated artifacts consistently updated.

Job Architecture

The pipeline consists of four specialized jobs running on ubuntu-latest runners: audit, readme-counts-sync, site-rebuild, and readme-counts-drift. Each job executes specific Python or Node.js scripts located in the scripts/ and site/ directories to enforce curriculum standards and update derived files.

The Four Jobs Explained

Audit Job

The audit job executes scripts/audit_lessons.py to enforce lesson-level rules including file layout, naming conventions, required files, and test count validation. This job runs on every push and pull request, failing the entire workflow if any curriculum contract violation is detected. The script verifies mandatory lesson components such as docs/en.md, code/main.*, quiz.json, and associated test suites.

README Counts Sync

Triggered exclusively on pushes to main, the readme-counts-sync job runs scripts/build_catalog.py to rebuild the lesson catalog, followed by scripts/check_readme_counts.py --fix to automatically correct lesson count tables in README.md. This blocking job ensures the repository's public documentation always reflects the true number of lessons per phase without manual intervention.

Site Rebuild

Also triggered on main branch pushes, the site-rebuild job regenerates the static site data by executing node site/build.js. The generated site/data.js file is committed automatically by the CI pipeline, ensuring the public website always displays the latest curriculum structure and metadata.

README Counts Drift

The readme-counts-drift job runs exclusively on pull requests, executing scripts/check_readme_counts.py without the --fix flag. This advisory gate warns contributors when their changes would cause README desynchronization, encouraging developers to run the fix locally before merging while preventing automated modifications to pull request branches.

Implementation Details

The workflow definition follows standard GitHub Actions YAML syntax with conditional execution logic. Below is the structural pattern for the audit job, which illustrates the installation of Python dependencies and script execution:

name: curriculum

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Python deps
        run: pip install -r requirements.txt
      - name: Run lesson audit
        run: python3 scripts/audit_lessons.py

The remaining jobs follow similar patterns with additional if conditions (such as if: github.event_name == 'push' && github.ref == 'refs/heads/main') to differentiate between PR validation and main branch deployment tasks.

Summary

• The audit job enforces curriculum structure compliance through scripts/audit_lessons.py on every push and pull request.
• readme-counts-sync automatically updates lesson catalogs and README tables using scripts/build_catalog.py and scripts/check_readme_counts.py --fix when code reaches the main branch.
• site-rebuild regenerates site/data.js via node site/build.js to keep the public website current with the latest curriculum data.
• readme-counts-drift provides early warnings on pull requests to prevent documentation synchronization issues without automatically modifying files.
• All jobs execute on ubuntu-latest runners and rely on Python 3 and Node.js scripts stored in the scripts/ and site/ directories.

Frequently Asked Questions

What triggers the curriculum.yml workflow?

The workflow triggers on every push to the main branch and every pull request event. This configuration ensures continuous integration validation for incoming changes and continuous deployment for merged updates to the curriculum.

How does the workflow validate lesson structure?

The audit job runs scripts/audit_lessons.py to verify that each lesson contains mandatory files including docs/en.md, code/main.*, quiz.json, and appropriate test suites. The script checks file layouts, naming conventions, and test counts, causing immediate workflow failure upon detection of any violation.

Why are there two different jobs for README count checking?

The readme-counts-sync job runs on the main branch with the --fix flag to automatically correct discrepancies in README.md, while readme-counts-drift runs on pull requests without the fix flag to warn contributors about documentation drift. This separation prevents the CI system from committing changes directly to pull request branches while maintaining automation on the main branch.

What file does the site-rebuild job generate?

The site-rebuild job executes node site/build.js to generate site/data.js, a JSON data file consumed by the static website frontend to render the current curriculum structure, lesson metadata, and navigation elements.

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