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

> Explore the curriculum.yml CI workflow gates audit, readme-counts-sync, site-rebuild, and readme-counts-drift to automate lesson validation and documentation sync in AI Engineering.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: internals
- Published: 2026-09-01

---

**The [`curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.

```yaml
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.

```yaml
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) file directly to the repository, guaranteeing that the deployed site always matches the source curriculum metadata.

```yaml
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.

```yaml
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:

```yaml
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml)**: Defines the orchestration logic, job dependencies, and conditional execution rules for all four gates.
- **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)**: Performs structural validation including lesson metadata, required files, and dependency verification.
- **[`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py)**: Calculates lesson statistics and updates README tables; accepts the `--fix` flag for automatic correction.
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)**: Compiles curriculum metadata into static site assets.
- **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.