Module 1: Introduction to CI/CD and GitHub Actions

1. Introduction to CI/CD and GitHub Actions

Next →

Overview

Every time you make a change to your AI application, what happens? You push to the repo, run the tests manually (if you remember), and deploy with ssh + git pull + docker-compose up + crossing your fingers. A change in your system prompt could degrade responses without anyone noticing. An updated pip install could break your Dockerfile. And there's no way to know until a user complains.

CI/CD (Continuous Integration / Continuous Deployment) turns this artisanal flow into an automated pipeline. In this module you're going to understand what problem it solves, why AI applications need it more than traditional software, and you're going to create your first workflow with GitHub Actions — the platform that automates all of this directly from your GitHub repository.

Context: Where are we in the guide?

This is Guide #16 of the AI Engineering Path — the second advanced-level guide. You get here after:

  • ✅ Git & GitHub (#4): Fluent handling of repos, branches, PRs
  • ✅ Production Best Practices (#13): Testing with pytest, fixtures, markers
  • ✅ Docker Essentials (#15): Containerization, Docker Compose, multi-stage builds

You have the tools. What's missing is the automation that connects them.

ModuleWhat you'll learn
Module 1CI/CD concepts + GitHub Actions basics + first workflow
Module 2Automated testing in CI (pytest, matrix, caching)
Module 3AI-specific checks (prompt regression, cost estimation)
Module 4Secrets and environment management
Module 5Automated Docker build and push in CI
Module 6Deployment pipelines (staging → approval → production)
Module 7Notifications, scheduled workflows, reusable workflows
Module 8Capstone project — production-grade pipeline

Module objective

By completing this module you'll be able to:

  • ✅ Explain what CI and CD are, and why AI systems need them more than traditional software
  • ✅ Describe the anatomy of a GitHub Actions workflow: workflows, jobs, steps, runners
  • ✅ Read and write YAML for workflows without indentation errors
  • ✅ Configure triggers: push, pull_request, schedule, workflow_dispatch
  • ✅ Create a working workflow from scratch: checkout → setup python → run script
  • ✅ Interpret GitHub Actions logs to debug failures
  • ✅ Run a workflow in your own repository and verify results

Mental model of the module

Before getting into detail, this is the conceptual structure of what you're going to learn. Think of this module as three blocks built one on top of the other:

┌─────────────────────────────────────────────────────┐
│  BLOCK 3: BUILD                                     │
│  Capsules 06-08                                     │
│  Create, run and debug your first workflow          │
│                                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │  BLOCK 2: UNDERSTAND                        │    │
│  │  Capsules 03-05                             │    │
│  │  Architecture, YAML, triggers               │    │
│  │                                             │    │
│  │  ┌─────────────────────────────────────┐    │    │
│  │  │  BLOCK 1: CONTEXT                   │    │    │
│  │  │  Capsules 01-02                     │    │    │
│  │  │  What is CI/CD? Why AI?             │    │    │
│  │  └─────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

The learning flow is deliberate:

Context (why) → Concepts (what) → Syntax (how to write it) → Practice (do it)
      ↓                 ↓                   ↓                       ↓
  Capsules 01-02    Capsule 03        Capsules 04-05          Capsules 06-08

You're not going to write YAML until you understand the architecture. You're not going to create a workflow until you master the YAML. Each capsule unlocks the next one.

Prerequisites

Required knowledge

  • ✅ Fluent Git & GitHub: You know how to push, create branches, open PRs, navigate GitHub's UI
  • ✅ Intermediate Python: You can write scripts, install dependencies with pip, use requirements.txt
  • ✅ Basic terminal: You feel comfortable running commands in the terminal
  • ✅ Basic Docker: You understand what a Dockerfile and a container are (from guide #15)

Optional but useful

  • Experience with pytest (from guide #13)
  • Having created a project with FastAPI

Quick check

If you can answer these 5 questions correctly, you're ready for the module:

1. What command do you use to send your local commits to GitHub?

See answer

git push origin <branch>. If you have the upstream configured, git push is enough. If you don't know what an upstream is, review Guide #4 — you'll need it for GitHub Actions to detect your pushes.

2. How do you install the dependencies listed in a requirements.txt?

See answer

pip install -r requirements.txt. This command reads the file line by line and installs each package. In CI, this step runs automatically inside the runner — that's why it's important that your requirements.txt is up to date and works without manual intervention.

3. What is a Pull Request and what is it for?

See answer

A Pull Request (PR) is a proposed change on GitHub. You create a branch, make commits, and open a PR so that someone (or something, like a CI workflow) reviews the changes before merging to the main branch. In this module you're going to configure workflows that run automatically when a PR is opened.

4. What's the difference between a Dockerfile and a container?

See answer

A Dockerfile is the recipe (build instructions). A container is the result of running that recipe — an isolated environment running your application. In Module 5 you're going to automate the build and push of Docker images inside CI, so you need to be clear on this concept.

5. Can you create a Python file, run it from the terminal and verify the output?

See answer

Something like: create hello.py with print("works"), run python hello.py, and see works in the terminal. It seems trivial, but your first GitHub Actions workflow does exactly this — it runs a Python script and verifies the output. If you can do it locally, you can do it in CI.

Module content

These are the 8 capsules that make up this module:

Capsule 02: What CI/CD is and why AI needs it — ~30 min

The full picture: what Continuous Integration is, what Continuous Deployment/Delivery is, and why AI applications — with their non-determinism, cost risks, and prompt fragility — need it more than traditional software.

Capsule 03: GitHub Actions — Architecture and concepts — ~35 min

How GitHub Actions works under the hood: workflows, jobs, steps, runners, and how they connect. The mental model you need before writing your first YAML.

Capsule 04: YAML Syntax for Workflows — ~40 min

YAML isn't optional — it's the language of GitHub Actions. Indentation with spaces, arrays with dashes, nested maps, strings with special characters. The most common errors and how to avoid them.

Capsule 05: Triggers — Push, PR, Schedule — ~30 min

When your workflow runs: push, pull_request, schedule (cron), workflow_dispatch (manual). Each trigger has a specific use case — you'll learn when to use each one.

Capsule 06: Your First Workflow Step by Step — ~45 min

Hands on the code. You create your first workflow from scratch: checkout the code, set up Python, install dependencies, run a script. You see the complete cycle: push → workflow runs → result on GitHub.

Capsule 07: Debugging Workflows — ~35 min

Workflows are going to fail. You learn to read Actions logs, identify which step failed, interpret error messages, and the tools to debug without losing your mind.

Capsule 08: Project — First CI Workflow — ~60 min

The module's capstone project. You create a complete workflow that runs on every push to your repository: checkout, setup Python, install dependencies, run script, and you verify that it works in GitHub's Actions tab.

Total estimated module time: ~4.5 hours

Each capsule is designed to be completed in a single session. If you have previous experience with YAML or CI, the conceptual capsules will take you less time and you'll be able to spend more on the practical ones.

Connection with the guide's project

Everything you learn in this module is the foundation of the pipeline you'll build throughout the guide:

Module 1: Basic workflow (this module)
    ↓
Module 2: + Automated testing
    ↓
Module 3: + AI-specific checks
    ↓
Module 4: + Secrets management
    ↓
Module 5: + Docker build & push
    ↓
Module 6: + Deployment staging → production
    ↓
Module 7: + Notifications & advanced patterns
    ↓
Module 8: Production-grade capstone pipeline

Your first workflow is intentionally simple. The simplicity is the point: you need to see the complete cycle working (push → something happens automatically → visible result) before adding complexity. Each later module adds a capability on top of this base.

Technical setup

What you need installed

# Check Git
git --version
# Expected: git version 2.39+ (any recent version works)

# Check Python
python --version
# Expected: Python 3.10+ (3.12 recommended)

# Check pip
pip --version
# Expected: pip 23+

Step-by-step verification

After checking the versions, make sure each tool works correctly:

# 1. Git: check that you can connect to GitHub
git ls-remote https://github.com/octocat/Hello-World.git HEAD
# If you see a SHA hash → Git + connection to GitHub work

# 2. Python: check that it runs scripts
python -c "print('Python OK')"
# Expected output: Python OK

# 3. pip: check that it can install packages
pip install --dry-run pytest
# If you see no errors → pip works correctly
# (--dry-run doesn't install anything, it just simulates)

What you need on GitHub

  • ✅ A GitHub account (free tier is enough)
  • ✅ A repository where you can push (public or private)
  • ✅ Access to the repository's Actions tab

Note: GitHub Actions has a free tier of 2,000 minutes/month for private repos and unlimited minutes for public repos. For this guide, the free tier is more than enough.

Common setup problems and how to solve them

Actions disabled in the repository

If you don't see the "Actions" tab in your GitHub repository, it's probably disabled:

  1. Go to your repository → Settings → Actions → General
  2. Select "Allow all actions and reusable workflows"
  3. Click Save

If the repository belongs to an organization, the organization admin needs to enable Actions at the organization level first.

python doesn't work but python3 does

On macOS and some Linux distributions, the python command doesn't exist by default — only python3. Two options:

# Option 1: Create an alias (temporary, only for the current session)
alias python=python3

# Option 2: Check with python3 directly
python3 --version

In GitHub Actions workflows this isn't a problem: the actions/setup-python action configures python correctly on the runner.

Push rejected due to authentication

If git push fails with an authentication error, you need to configure an authentication method with GitHub:

# Check whether you have SSH configured
ssh -T git@github.com
# Expected: "Hi <username>! You've successfully authenticated..."

# If not, use HTTPS with a token
# Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Generate new token

pip shows permission warnings

If you see WARNING: Running pip as the 'root' user, use a virtual environment:

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

Recommended project structure

To follow this guide, I recommend having a Python project with this minimal structure:

my-ai-project/
├── .github/
│   └── workflows/       # Your workflows go here (you'll create it in this module)
├── src/
│   └── main.py          # Your main code
├── tests/
│   └── test_main.py     # Your tests (you'll use them in Module 2)
├── requirements.txt     # Dependencies
└── README.md

If you already have an AI project from previous guides (FastAPI + OpenAI, for example), use it. If not, create a basic one:

mkdir my-ai-project
cd my-ai-project
git init

mkdir -p .github/workflows src tests

# Minimal main file
cat > src/main.py << 'EOF'
def greet(name: str) -> str:
    return f"Hello, {name}! Welcome to CI/CD for AI."

if __name__ == "__main__":
    print(greet("AI Engineer"))
EOF

# Minimal test
cat > tests/test_main.py << 'EOF'
from src.main import greet

def test_greet():
    result = greet("World")
    assert result == "Hello, World! Welcome to CI/CD for AI."

def test_greet_empty():
    result = greet("")
    assert "Hello, " in result
EOF

# Minimal dependencies
cat > requirements.txt << 'EOF'
pytest>=8.0
EOF

# README
echo "# My AI Project - CI/CD Learning" > README.md
# Check that it works locally
pip install -r requirements.txt
python src/main.py
# Expected output: Hello, AI Engineer! Welcome to CI/CD for AI.

pytest tests/ -v
# Expected output: 2 tests passed

Quick test: does everything work?

If you made it this far, run this final checklist to confirm your environment is ready:

# Complete checklist in 4 commands
git --version && echo "✅ Git OK"
python --version && echo "✅ Python OK"
pip --version && echo "✅ pip OK"
cd my-ai-project && pytest tests/ -v && echo "✅ Tests OK"

If the 4 commands pass without errors, your local environment is ready. The next step is to verify that your GitHub repository has Actions enabled — you'll do that in Capsule 06 when you create your first workflow.

Versions and compatibility

GitHub Actions runs your workflows on runners — virtual machines that GitHub provisions automatically. It's important that your local environment and the runner use compatible versions.

GitHub Actions runners

RunnerOperating systemUse in this guide
ubuntu-latestUbuntu 22.04 (currently)Recommended for this guide
ubuntu-24.04Ubuntu 24.04Valid alternative
macos-latestmacOS 14 (Sonoma)Works, but consumes more free-tier minutes
windows-latestWindows Server 2022Not recommended for this guide

ubuntu-latest is the standard for CI/CD in Python. It consumes 1x minute per minute of execution. macOS runners consume 10x and Windows 2x, so for the guide we use Linux exclusively.

Python versions

In your workflows you're going to specify which Python version to use with the actions/setup-python action:

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
VersionStatusRecommendation
3.10SupportedMinimum for this guide
3.11SupportedWorks well
3.12SupportedRecommended
3.13SupportedWorks, but some libraries might have issues

The recommendation is to use 3.12 both in your local environment and in CI. This avoids "works on my machine but fails in CI" problems caused by version differences.

Versioned actions

Third-party actions (like actions/checkout and actions/setup-python) use semantic versioning with major version tags:

- uses: actions/checkout@v4       # Major version 4
- uses: actions/setup-python@v5   # Major version 5

Always use the most recent major version. GitHub's actions are updated with backward compatibility within the same major version, so @v4 automatically gives you the latest 4.x.x version.

What this module does NOT cover

  • ❌ Automated testing in CI: That's Module 2 (pytest in Actions, matrix testing)
  • ❌ AI-specific checks: That's Module 3 (prompt regression, cost estimation)
  • ❌ Secrets management: That's Module 4 (API keys in CI)
  • ❌ Docker in CI: That's Module 5 (automatic build and push)
  • ❌ Deployment: That's Module 6 (staging → production)
  • ❌ Other CI platforms: This guide uses GitHub Actions exclusively (not Jenkins, GitLab CI, or CircleCI)

The decision to focus on GitHub Actions is deliberate: it's the most widely adopted platform, it has a generous free tier, and it integrates natively with GitHub — which you already use.

Evidence of success

By the end of this module, you should be able to:

  • Explain in one sentence what CI is and what CD is
  • Draw the relationship between workflow, job and step
  • Write a valid YAML file for GitHub Actions with no syntax errors
  • Create a workflow that runs automatically on every push
  • Navigate GitHub's Actions tab and read the logs of a workflow run
  • Debug a failed workflow by identifying the problematic step

If you check all the boxes → you're ready for Module 2.

Next module

Module 2 (Automated Testing in CI) takes the basic workflow you create here and turns it into a real testing pipeline: automated pytest, matrix testing for multiple Python versions, dependency caching, and test reports. The transition is direct: "You already have a workflow that runs on every push → now let's make it run your tests automatically."

Additional resources

  1. GitHub Actions Documentation - Complete official documentation
  2. GitHub Actions Quickstart - Official getting started
  3. Understanding GitHub Actions - Fundamental concepts
  4. YAML Specification - Official YAML spec
  5. GitHub Actions Free Tier - Pricing details and limits
  6. GitHub Actions Marketplace - Reusable actions from the community
Next →2. What CI/CD Is and Why AI Needs It