Understanding the curriculum.yml CI Workflow Gates in AI-Engineering-From-Scratch

The curriculum.yml workflow defines four distinct CI gates—audit, readme-counts-sync, site-rebuild, and readme-counts-drift—that automatically validate lesson integrity, synchronize documentation, and rebuild the static site based on specific GitHub events.

The rohitg00/ai-engineering-from-scratch repository uses a sophisticated continuous integration pipeline defined in .github/workflows/curriculum.yml to maintain curriculum quality. These curriculum.yml CI workflow gates function as automated checkpoints that trigger on every push and pull request, ensuring only properly structured lessons merge into the main branch while keeping the public website and README statistics synchronized without manual intervention.

What Are the CI Workflow Gates?

In the context of this repository, gates are discrete GitHub Actions jobs that enforce specific quality controls. Each gate focuses on a single responsibility—from validating lesson structure to regenerating static assets—and uses conditional logic to determine whether it runs on pull requests, main branch pushes, or both. This separation ensures that blocking checks run immediately while maintenance tasks execute only when code reaches the main branch.

The Four Gates Explained

The Audit Gate (Blocking)

The audit gate serves as the primary quality checkpoint. Triggered on every push and pull_request event, this job executes scripts/audit_lessons.py to perform structural validation, dependency checks, and documentation verification on every lesson. Because this gate runs on all branches and PRs, it acts as a blocking requirement—pull requests cannot be merged until the audit passes successfully.

audit:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - name: Run lesson audit
      run: python3 scripts/audit_lessons.py

README Counts Sync (Main Branch Only)

The readme-counts-sync gate automatically maintains the lesson count tables in README.md. This job runs exclusively on the main branch, as specified by the condition if: github.ref == 'refs/heads/main'. When triggered by a push to main, it executes scripts/check_readme_counts.py --fix to regenerate the catalog and automatically commit any fixes to the documentation.

readme-counts-sync:
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - name: Sync README counts
      run: python3 scripts/check_readme_counts.py --fix

Site Rebuild (Main Branch Only)

The site-rebuild gate ensures the public website reflects the latest curriculum state. Also restricted to the main branch via the same conditional check, this job runs node site/build.js to regenerate the static site data. The process commits the resulting site/data.js file directly to the repository, guaranteeing that the deployed site always matches the source curriculum metadata.

site-rebuild:
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - name: Rebuild site
      run: node site/build.js

README Counts Drift (Advisory)

The readme-counts-drift gate provides non-blocking feedback during the pull request process. Triggered only on pull_request events (if: github.event_name == 'pull_request'), this job runs scripts/check_readme_counts.py without the --fix flag to detect discrepancies between the actual lesson structure and the README tables. Unlike the sync gate, this check does not block merges—it simply alerts reviewers that documentation updates will be needed upon merge.

readme-counts-drift:
  if: github.event_name == 'pull_request'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - name: Advisory count check
      run: python3 scripts/check_readme_counts.py

How the Gates Trigger

The workflow uses the on: configuration block to listen for repository events across all branches:

name: curriculum
on:
  push:
    branches: [main, '**']
  pull_request:
    branches: [main, '**']

This configuration ensures that all gates evaluate every change, though individual jobs execute only when their specific conditions match. The audit and readme-counts-drift gates provide immediate feedback during development, while the readme-counts-sync and site-rebuild gates execute automatically upon merging to main, eliminating the need for manual release steps.

Key Implementation Files

• .github/workflows/curriculum.yml: Defines the orchestration logic, job dependencies, and conditional execution rules for all four gates.
• scripts/audit_lessons.py: Performs structural validation including lesson metadata, required files, and dependency verification.
• scripts/check_readme_counts.py: Calculates lesson statistics and updates README tables; accepts the --fix flag for automatic correction.
• site/build.js: Compiles curriculum metadata into static site assets.
• AGENTS.md: Documents the operational policies and CI/CD architecture for repository maintainers.

Summary

• The audit gate runs on every push and pull request, blocking merges that fail structural or dependency validation in scripts/audit_lessons.py.
• The readme-counts-sync gate executes only on the main branch, automatically fixing lesson count tables in the README.
• The site-rebuild gate regenerates the static website via node site/build.js exclusively after changes reach the main branch.
• The readme-counts-drift gate provides advisory warnings on pull requests without blocking merges, alerting reviewers to upcoming documentation changes.
• All gates are defined in .github/workflows/curriculum.yml and use GitHub Actions conditional logic to target specific branches and event types.

Frequently Asked Questions

What makes the audit gate different from the other curriculum.yml CI workflow gates?

The audit gate is the only blocking gate that runs on pull requests. While readme-counts-drift provides advisory feedback and the other gates run only after merge, the audit gate executes scripts/audit_lessons.py immediately on every PR and must pass before GitHub allows the merge to complete.

Why do some gates only run on the main branch?

The readme-counts-sync and site-rebuild gates are restricted to the main branch using the condition if: github.ref == 'refs/heads/main' to prevent redundant site builds and documentation commits on feature branches. This ensures that public-facing assets update only when curriculum changes are finalized and merged.

How does the curriculum.yml workflow handle README synchronization?

The workflow uses two complementary gates: readme-counts-drift detects discrepancies during PR review, while readme-counts-sync automatically fixes the tables upon merging to main. Both gates execute scripts/check_readme_counts.py, but the sync version passes the --fix flag to enable automatic commits.

Where is the CI/CD behavior documented for this repository?

The operational manual for these gates is documented in AGENTS.md at the repository root. This file explains the architectural decisions behind the gate structure, the role of each script, and the automated maintenance policies that keep the curriculum repository synchronized.

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