CI/CD and GitHub Actions: automated testing of a Django project¶
This file is a self-contained reference on CI/CD in the context of Django Testing. It explains: what CI/CD is, how GitHub Actions works, how to read the existing
django-tests.ymlin our project, and how all of this relates to the tests you are already writing.
Contents¶
Concepts - 1. The problem CI/CD solves - 2. What CI/CD is - 3. Continuous Integration vs Continuous Delivery vs Continuous Deployment
GitHub Actions - 4. GitHub Actions components - 5. How to read a YAML workflow - 6. Our django-tests.yml — line by line - 7. Events — when to run - 8. Jobs and Steps — what runs and how - 9. Actions — ready-made building blocks - 10. Runners — where the code runs
Practice - 11. How to view results on GitHub - 12. CI/CD and the testing pyramid - 13. GitHub Pages — publishing a static site - 14. Common errors and how to read them - 15. Self-check questions
1. The problem CI/CD solves¶
Imagine this situation. You wrote a function create_note_for_user. It passed the local tests. You did git push. Two hours later it turns out that the form on the registration page no longer saves data.
How does that happen? You didn't touch the form. But somewhere a change in the service layer pulled in a dependency you didn't see.
Without automation, this chain looks like this:
Developer A Developer B Deploy to production
writes feature ─┐ writes feature ─┐
│ │
└── manual merge ───┴── manual tests ── manual deploy
(merge conflicts!) (someone forgot) (2+ hrs of rituals)
And then there's a bug in production. And nobody knows exactly whose change caused it.
This is exactly what CI/CD solves: every git push automatically runs the full test suite on a clean server. If the tests pass, the code is safe to merge. If they fail, the developer sees it before the code ever reaches main.
2. What CI/CD is¶
CI/CD stands for Continuous Integration / Continuous Delivery (or Deployment).
It is not a single tool or a single button. It is a way of organizing a team's work so that testing and deployment happen automatically after every change.
In short:
| Abbreviation | Name | What it does |
|---|---|---|
| CI | Continuous Integration | Automatically builds and tests the code after every push |
| CD | Continuous Delivery | Automatically prepares a build for production — but a human deploys it |
| CD | Continuous Deployment | Automatically deploys to production without human involvement |
The difference between Delivery and Deployment comes down to one word: human. In Delivery, a human clicks the confirm button. In Deployment, nobody does.
An important idea:
CI/CD is not about tools. It is about tests running automatically and feedback arriving quickly.
3. Continuous Integration vs Continuous Delivery vs Continuous Deployment¶
A detailed diagram:
flowchart LR
subgraph CI["Continuous Integration"]
direction LR
A[git push] --> B["Build<br>Install deps"]
B --> C["Lint<br>Type check"]
C --> D["Unit Tests<br>Integration Tests"]
D --> E{Passed?}
E -- yes --> F[Notify: OK]
E -- no --> G["Block PR<br>Notify: Failed"]
end
subgraph DELIVERY["Continuous Delivery"]
direction LR
H[Artifact ready] --> I[Deploy: Staging]
I --> J[Smoke Tests]
J --> K{OK?}
K -- yes --> L[Human approves]
L --> M[Deploy: Production]
K -- no --> N[Rollback Staging]
end
subgraph DEPLOYMENT["Continuous Deployment"]
direction LR
O[Artifact ready] --> P[Deploy: Staging]
P --> Q[Automated Tests]
Q --> R{OK?}
R -- yes --> S[Auto Deploy: Production]
R -- no --> T[Auto Rollback]
end
CI --> DELIVERY
CI --> DEPLOYMENT
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef decision fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
classDef error fill:#ffebee,stroke:#c62828,stroke-width:3px;
classDef warning fill:#fff8e1,stroke:#e65100,stroke-width:2px;
class A,B,C,D,H,I,J,O,P,Q step;
class E,K,R decision;
class F,M,S success;
class G,N,T error;
class L warning;
Where is our notes_chat_app right now? At the CI level: every push to main runs the tests. Deployment is not automated yet — but this is the first and most important step.
4. GitHub Actions components¶
GitHub Actions is a CI/CD platform built right into GitHub. No third-party services are needed.
The component hierarchy:
Repository
└── .github/
└── workflows/
└── django-tests.yml ← Workflow
│
├── on: push ← Event (trigger)
│
└── jobs:
├── unit-and-integration: ← Job 1
│ ├── step 1 ← Step: checkout
│ ├── step 2 ← Step: setup-python
│ └── step 3 ← Step: manage.py test
│
└── selenium-e2e: ← Job 2 (needs: unit-and-integration)
├── step 1
└── step 2
| Component | What it is | Analogy |
|---|---|---|
| Workflow | The whole scenario in a YAML file | The script of a play |
| Event | The trigger that starts the workflow | The curtain rises |
| Job | A set of steps on one runner | An act of the play |
| Step | One command or action | A single scene |
| Action | A ready-made reusable step | A prop from a store |
| Runner | The server where the code runs | The stage |
5. How to read a YAML workflow¶
A workflow is a YAML file. Here is a minimal example with explanations:
name: Django Tests # Name (shown in GitHub → Actions)
on: # When to run
push:
branches: [main] # On push to main
jobs: # What to do
test: # Job name
runs-on: ubuntu-latest # On which OS
steps: # Steps in order
- uses: actions/checkout@v4 # Clone the repository
- uses: actions/setup-python@v5 # Install Python
with:
python-version: "3.12"
- run: pip install -r requirements.txt # Shell command
- run: python manage.py test # Run the tests
Reading rules:
- uses: — use a ready-made action (from the marketplace)
- run: — run a shell command
- with: — parameters for an action
- needs: — this job waits for another one
- env: — environment variables
6. Our django-tests.yml — line by line¶
Our project already has a workflow:
Note: the Django project (manage.py, requirements.txt) sits right in the repository root, so the workflow lives in the root .github/workflows/ too, and GitHub runs it automatically. GitHub ignores a workflow placed in any other folder (for example, inside docs/). There is only one correct place:
Let's go through it piece by piece.
Triggers¶
on:
push:
branches: [ main, master ] # push to main or master
pull_request:
branches: [ main, master ] # PR to main or master
workflow_dispatch: # manual run via a button in the UI
In the real file, push and pull_request also have a paths: filter (notes_app/**, notes_project/**, templates/**, static/**, requirements.txt and the workflow itself): changes that touch only the documentation do not run the tests.
What happens: if someone opens a Pull Request to main → GitHub sees on: pull_request → runs the workflow → the result (green/red) appears right in the PR.
Job 1: Unit + Integration tests¶
jobs:
unit-and-integration:
name: Unit, Integration & Consumer Tests
runs-on: ubuntu-latest
services:
db:
image: postgres:16-alpine
env:
POSTGRES_DB: notes_db
POSTGRES_USER: notes_user
POSTGRES_PASSWORD: notes_pass
ports:
- 5432:5432
# ... health-check options (pg_isready)
env:
DATABASE_URL: postgres://notes_user:notes_pass@localhost:5432/notes_db
ubuntu-latest is a fresh VM on Azure that is destroyed after every run. There is no state between runs.
services.db is a PostgreSQL container next to the runner: the project works only with PostgreSQL, so the tests get their database through DATABASE_URL.
The first step is always the same: clone the repository onto the VM. Without this step, the runner doesn't have your code at all.
- name: Cache pip dependencies
uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
A cache of pip dependencies. If requirements.txt hasn't changed, pip packages are loaded from the cache instead of the internet. This speeds up the pipeline from 3 minutes to 1 minute.
manage.py check is a built-in Django command. It checks the configuration, models, and middleware without starting the server. If you have an error in settings.py, you'll find out before the tests even run.
- name: Run unit, integration and consumer tests
run: |
python manage.py test \
notes_app.tests.test_models \
notes_app.tests.test_services \
notes_app.tests.test_forms \
notes_app.tests.test_views \
notes_app.tests.test_consumers \
-v 2
Runs all tests except Selenium (those are in a separate job), including the WebSocket tests in test_consumers. The -v 2 parameter means verbose — it shows the name of every test.
- name: Generate coverage report
run: |
coverage run manage.py test ...
coverage report --show-missing
coverage xml -o coverage.xml
Coverage: runs the tests via coverage run to track which lines of code were executed. coverage xml generates a file for integration with services such as Codecov.
- name: Upload coverage report
uses: actions/upload-artifact@v4
with:
name: coverage-xml
path: coverage.xml
Saves coverage.xml as an artifact — a file you can download through the GitHub UI after the workflow finishes.
Job 2: Selenium E2E¶
selenium-e2e:
name: Selenium E2E Tests
needs: unit-and-integration # Run AFTER the "unit-and-integration" job succeeds
runs-on: ubuntu-latest
services:
db:
image: postgres:16-alpine
# ... the same as in Job 1
selenium:
image: selenium/standalone-chrome:latest
ports:
- 4444:4444
options: >-
--add-host=host.docker.internal:host-gateway
--shm-size=2gb
# ... health-check options
env:
DATABASE_URL: postgres://notes_user:notes_pass@localhost:5432/notes_db
SELENIUM_REMOTE_URL: http://localhost:4444/wd/hub
WEB_HOST: host.docker.internal
services are Docker containers that start alongside the runner. Selenium/standalone-chrome runs Chrome in headless mode. Our test connects to it via http://localhost:4444. --add-host=host.docker.internal:host-gateway together with WEB_HOST=host.docker.internal lets Chrome inside the container open the Django test server running on the runner.
steps:
# ... checkout, setup-python, cache, pip install
- name: Run Selenium E2E tests
run: python manage.py test notes_app.tests.test_selenium -v 2
SELENIUM_REMOTE_URL is an environment variable read by _make_headless_driver() in notes_app/tests/test_selenium.py. WEB_HOST is read by _DockerLiveServerMixin: it binds the test server to 0.0.0.0 and puts host.docker.internal into live_server_url. If it is set, Selenium connects to a Remote WebDriver instead of a local browser.
7. Events — when to run¶
The most commonly used triggers:
on:
# On push to specific branches
push:
branches: [main, develop]
paths: ['notes_app/**', 'tests/**'] # Only if these files changed
# When a PR is opened or updated
pull_request:
types: [opened, synchronize, reopened]
# On a schedule (cron syntax)
schedule:
- cron: '0 6 * * 1' # Every Monday at 6:00 UTC
# Manual run via the GitHub UI
workflow_dispatch:
# When a release is published
release:
types: [published]
Practical tip: for a learning project, push and pull_request are enough. schedule is useful for nightly full test runs, and release for deploying when a version is published.
8. Jobs and Steps — what runs and how¶
Parallelism and dependencies¶
By default, jobs run in parallel. needs changes that:
jobs:
lint: # Starts immediately
...
test: # Starts immediately (in parallel with lint)
...
test-selenium:
needs: test # Waits for test
...
deploy:
needs: [lint, test] # Waits for BOTH
...
What it looks like over time:
Time: 0s 30s 60s 90s
│ │ │ │
lint ├───────────┤
test ├───────────────────────┤
selenium ├───────────┤
deploy (won't start until lint and test pass)
Conditional execution¶
steps:
- name: Deploy (only on success)
if: success()
run: ./deploy.sh
- name: Notify about a failure (any failure)
if: failure()
run: ./notify.sh
- name: Clean up temp files (always)
if: always()
run: rm -rf /tmp/test_*
- name: Deploy only from main
if: github.ref == 'refs/heads/main'
run: ./deploy.sh
9. Actions — ready-made building blocks¶
Actions are reusable steps from the GitHub Marketplace.
The most commonly used ones in Django projects¶
# Clone the repository (always the first step)
- uses: actions/checkout@v4
# Install Python with a pip cache
- uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: 'pip' # Caches pip automatically
# Manual cache (more control)
- uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
# Save a file as an artifact
- uses: actions/upload-artifact@v4
with:
name: test-results
path: coverage.xml
retention-days: 7 # Keep for 7 days
# Download an artifact in another job
- uses: actions/download-artifact@v4
with:
name: test-results
Passing data between Jobs¶
Jobs do not share a file system. To pass data, use artifacts or outputs:
jobs:
build:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.ver.outputs.version }}
steps:
- id: ver
run: echo "version=$(cat VERSION)" >> $GITHUB_OUTPUT
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- run: echo "Deploying ${{ needs.build.outputs.version }}"
10. Runners — where the code runs¶
GitHub-hosted runners¶
| Runner | OS | CPU | RAM |
|---|---|---|---|
ubuntu-latest |
Ubuntu 22.04 | 2-core | 7 GB |
windows-latest |
Windows Server 2022 | 2-core | 7 GB |
macos-latest |
macOS 13 | 3-core | 14 GB |
For Django projects, always use ubuntu-latest — the fastest and cheapest.
What happens when you do git push¶
sequenceDiagram
participant DEV as Developer
participant GH as GitHub
participant VM as Runner VM (Azure)
DEV->>GH: git push main
GH->>GH: Detect workflow trigger
GH->>VM: Provision fresh Ubuntu VM
VM->>VM: actions/checkout → clone repo
VM->>VM: pip install -r requirements.txt
VM->>VM: python manage.py check
VM->>VM: python manage.py test -v 2
VM-->>GH: Test results
GH-->>DEV: ✅ All tests passed (or ❌ Failed)
GH->>VM: Terminate VM (ephemeral!)
Note over VM: The VM is destroyed. Next push gets a new clean VM.
An important detail: the VM is ephemeral — it is destroyed after every run. There is no "state" whatsoever between runs. If tests pass on the runner, they pass on a clean machine without your local settings.
11. How to view results on GitHub¶
- Open the repository on GitHub
- The Actions tab — a list of all workflow runs
- Click a specific run — you'll see the jobs graph
- Click a job — you'll see the list of steps
- Click a step — you'll see live logs
What the colors mean¶
| Color | Meaning |
|---|---|
| Green ✅ | The Step/Job finished successfully |
| Yellow 🟡 | The Step/Job is running right now |
| Red ❌ | The Step/Job failed |
| Gray ⏭ | The Step/Job was skipped (because of if: or needs:) |
Live logs — your best debugging tool¶
Each step expands into a full log with: - A timestamp for every line - The process's stdout and stderr - A "Download log archive" button
If a test fails, expand the test step and read the output the same way you read it locally.
12. CI/CD and the testing pyramid¶
Remember the pyramid from the "Testing pyramid" section?
In CI/CD, each level has its own role:
flowchart TD
PUSH([git push]) --> CI
subgraph CI["CI Pipeline"]
direction LR
L["Lint · ~30s<br>black, flake8"] --> U["Unit Tests · ~60s<br>test_models, test_services"]
U --> I["Integration Tests · ~90s<br>test_forms, test_views"]
I --> E["E2E Selenium · ~120s<br>test_selenium"]
end
CI --> STATUS{Status?}
STATUS -- ✅ All green --> MERGE[Safe to merge PR]
STATUS -- ❌ Lint failed --> FIX_LINT[Fix formatting]
STATUS -- ❌ Unit failed --> FIX_LOGIC[Fix business logic]
STATUS -- ❌ Integration failed --> FIX_VIEWS[Fix views/forms]
STATUS -- ❌ E2E failed --> FIX_E2E[Fix user flow]
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef decision fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
classDef error fill:#ffebee,stroke:#c62828,stroke-width:3px;
class PUSH,L,U,I,E step;
class STATUS decision;
class MERGE success;
class FIX_LINT,FIX_LOGIC,FIX_VIEWS,FIX_E2E error;
Why does the order matter? Lint fails within 30 seconds. If there's a formatting problem, you'll find out before you spend 5 minutes on a full run. "Fail fast" is a principle of good CI.
13. GitHub Pages — publishing a static site¶
GitHub Pages is a built-in way to publish a static site directly from a repository. Useful for Django documentation or a landing page.
Option 1: Publishing from a branch (simple)¶
Put HTML/CSS into the docs/ folder → push → the site is available at username.github.io/repo.
Option 2: Via GitHub Actions (flexible)¶
name: Deploy Documentation
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Build MkDocs site
run: |
pip install mkdocs mkdocs-material
mkdocs build
- uses: actions/upload-pages-artifact@v3
with:
path: ./site
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/deploy-pages@v4
id: deployment
Important limitations¶
⚠️ The site is PUBLICLY available on the internet — even if the repository is private.
⚠️ A CNAME file in the repository does NOT configure a custom domain.
The domain is changed only via Settings → Pages.
ℹ️ A push via GITHUB_TOKEN does not trigger a Pages rebuild
(protection against infinite recursion).
14. Common errors and how to read them¶
The workflow does not start¶
Symptom: the push was made, but there is no new run in the Actions tab
Causes:
- The YAML file is not in <repo-root>/.github/workflows/ (for example, it sits in docs/)
- A syntax error in the YAML (check the indentation)
- The branch does not match the filter in on.push.branches
Diagnosis: GitHub → Actions → "Check workflows", or look for the red icon
next to the commit in the commit list
Process completed with exit code 1¶
Symptom: The "Run unit tests" step is red, and the log shows:
FAIL: test_login_required (notes_app.tests.test_views.NoteListViewTest.test_login_required)
Cause: A test failed. That's normal — this is what CI is for.
Action: Expand the step → read the traceback → fix the code or the test
Permission denied / Resource not accessible¶
Symptom: The "Upload artifact" or "Deploy Pages" step is red
Cause: The workflow lacks the required permissions
Solution: Add at the top level of the YAML:
permissions:
contents: read
pages: write
id-token: write
Cache miss every time¶
Symptom: pip install takes 3 minutes on every run
Cause: the cache key keeps changing — maybe hashFiles picks the wrong file
Solution: Check the path:
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
↑ the glob looks for requirements.txt
in any subfolder
A secret is not passed into the environment¶
Symptom: The step fails with "API key not found" or "env var is None"
Cause: The secret exists in Settings but is not passed into the workflow
Solution:
- name: Deploy
env:
API_KEY: ${{ secrets.MY_API_KEY }} ← pass it explicitly
run: ./deploy.sh
15. Self-check questions¶
- How does CI differ from Continuous Delivery and Continuous Deployment?
- Why is the runner VM destroyed after every run — is it an advantage or a limitation?
- Why must
actions/checkout@v4be the first step? - Why is
needs: unit-and-integrationinselenium-e2eimportant? - What happens if
on: pushis specified withoutbranches: [main]? - Why cache pip dependencies if you could simply install them every time?
- Where is our
django-tests.ymllocated, and why does GitHub run it automatically? - What role does
SELENIUM_REMOTE_URLplay in Job 2, and where does the test code read this variable? - Why does lint run first in the pipeline and Selenium last?
- If a test fails in CI but passes locally — what should you check first?