Understanding the CI Jobs in curriculum.yml: Audit, Readme-Counts-Sync, and Site-Rebuild

The curriculum.yml workflow in rohitg00/ai-engineering-from-scratch orchestrates three essential CI jobs—audit, readme-counts-sync, and site-rebuild—that validate lesson integrity, synchronize README lesson counts, and regenerate the static site data on every push.

The curriculum.yml GitHub Actions workflow serves as the backbone of the AI-Engineering curriculum's continuous integration pipeline. Located at .github/workflows/curriculum.yml, this automation ensures that every change to the repository maintains data consistency across lesson files, documentation, and the public website. Understanding these three distinct jobs is critical for contributors who need to debug validation failures or extend the curriculum's automated checks.

The Audit Job: Continuous Validation of Curriculum Integrity

The audit job, defined at lines 75–112 of curriculum.yml, executes a comprehensive suite of invariant checks on every push or pull request. This job ensures that lesson files, certifications, scripts, and the generated site remain valid and internally consistent.

The workflow follows these sequential steps:

1. Checkout the repository with actions/checkout@v4 and configure persist-credentials: false for security.
2. Set up Python 3.12 using actions/setup-python@v5.
3. Execute scripts/audit_lessons.py to verify lesson-level invariants including missing files, naming conventions, and test coverage.
4. Run scripts/audit_certifications.py to validate certification lesson contracts and required assets.
5. Execute certification lab tests and demonstration scripts to verify functional correctness.
6. Validate skill bundles, static-site builds, SEO routes, agent readiness protocols, negotiation safety mechanisms, quiz de-biasing logic, and translation synchronization.

audit:
  name: invariant checks
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with: {persist-credentials: false}
    - uses: actions/setup-python@v5
      with: {python-version: "3.12"}
    - name: run scripts/audit_lessons.py
      run: python3 scripts/audit_lessons.py
    - name: run scripts/audit_certifications.py
      run: python3 scripts/audit_certifications.py

This job acts as the first line of defense against curriculum degradation, catching structural errors before they reach the main branch.

The Readme-Counts-Sync Job: Automated README Maintenance

The readme-counts-sync job, located at lines 125–162 of curriculum.yml, automatically corrects lesson-count tables in README.md and its internationalized translations on every push to main. This prevents documentation drift between the actual number of lessons in the repository and the counts displayed in the public-facing README.

The job executes the following workflow:

• Checkout the repository using a write-enabled token to enable automated commits.
• Install Python 3.12 and build a temporary curriculum catalog by executing scripts/build_catalog.py.
• Run scripts/check_readme_counts.py --fix to compute accurate lesson counts and rewrite the tables in README.md.
• Regenerate README translations by invoking scripts/build_readme_i18n.py.
• Commit and push changes only if the files differ from the previous state, avoiding empty commits.

readme-counts-sync:
  runs-on: ubuntu-latest
  needs: audit
  steps:
    - uses: actions/checkout@v4
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
    - uses: actions/setup-python@v5
      with: {python-version: "3.12"}
    - name: Build catalog
      run: python3 scripts/build_catalog.py
    - name: Fix README counts
      run: python3 scripts/check_readme_counts.py --fix

This automation ensures that contributors never need to manually update lesson statistics when adding or removing content from the curriculum.

The Site-Rebuild Job: Static Site Regeneration

The site-rebuild job, defined at lines 182–210 of curriculum.yml, regenerates the static site data file site/data.js after the README synchronization completes. This file powers the curriculum website's navigation, search functionality, and lesson metadata display.

Key characteristics of this job include:

• Dependency management: The job explicitly declares needs: readme-counts-sync to ensure it executes only after the README has been updated, preventing race conditions.
• Data generation: It runs site/build.js to produce a fresh site/data.js containing the latest curriculum structure.
• Conditional deployment: The workflow commits and pushes the regenerated data.js only when the file content changes, minimizing unnecessary repository activity.

site-rebuild:
  runs-on: ubuntu-latest
  needs: readme-counts-sync
  steps:
    - uses: actions/checkout@v4
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
    - name: Build site data
      run: node site/build.js
    - name: Commit and push if changed
      run: |
        git config --global user.name "github-actions"
        git config --global user.email "github-actions@github.com"
        git add site/data.js
        git diff --quiet && git diff --staged --quiet || git commit -m "Rebuild site data" && git push

This job ensures that the public curriculum website always reflects the current state of the repository within minutes of any merge to the main branch.

Summary

• The audit job validates curriculum integrity through invariant checks on lessons, certifications, and site builds using audit_lessons.py and audit_certifications.py.
• The readme-counts-sync job automatically updates lesson-count tables in README.md and translations via check_readme_counts.py --fix, preventing documentation drift.
• The site-rebuild job regenerates site/data.js using site/build.js only after README updates complete, ensuring website synchronization.
• Together, these jobs maintain lesson accuracy, documentation consistency, and website reliability for the AI-Engineering curriculum without manual intervention.

Frequently Asked Questions

What triggers the curriculum.yml workflow to execute?

The workflow triggers on every push to any branch and on pull requests targeting the main branch. The audit job runs on all these events, while readme-counts-sync and site-rebuild execute only on pushes to main to prevent partial updates during feature development.

How does the audit job detect broken lesson structures?

The audit job runs scripts/audit_lessons.py to check for missing files, incorrect naming conventions, and insufficient test coverage. It also executes scripts/audit_certifications.py to verify that certification lessons meet their contractual requirements and contain necessary assets before deployment.

What happens if the README lesson counts become out of sync?

The readme-counts-sync job detects discrepancies by comparing the actual lesson catalog against the tables in README.md. When it executes check_readme_counts.py --fix, it automatically recalculates the counts, updates the markdown tables, regenerates translations via build_readme_i18n.py, and commits the fixes directly to the repository.

Can these CI jobs be run locally for debugging purposes?

Yes, contributors can execute the underlying scripts locally. Run python3 scripts/audit_lessons.py and python3 scripts/audit_certifications.py for validation checks, python3 scripts/check_readme_counts.py --fix to update README tables, and node site/build.js to generate the site data file. Ensure Python 3.12 and Node.js are installed in your local environment.

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