CI/CD та GitHub Actions: автоматичне тестування Django-проєкту¶
Цей файл — самодостатній довідник по CI/CD у контексті Django Testing. Тут пояснено: що таке CI/CD, як влаштований GitHub Actions, як читати існуючий
django-tests.ymlу нашому проєкті, і як це все пов'язано з тестами, які ти вже пишеш.
Зміст¶
Концепції - 1. Проблема, яку вирішує CI/CD - 2. Що таке CI/CD - 3. Continuous Integration vs Continuous Delivery vs Continuous Deployment
GitHub Actions - 4. Компоненти GitHub Actions - 5. Як читати YAML workflow - 6. Наш django-tests.yml — рядок за рядком - 7. Events — коли запускати - 8. Jobs і Steps — що і як виконується - 9. Actions — готові блоки - 10. Runners — де виконується код
Практика - 11. Як переглянути результати в GitHub - 12. CI/CD і піраміда тестування - 13. GitHub Pages — публікація статичного сайту - 14. Типові помилки та як їх читати - 15. Питання для самоперевірки
1. Проблема, яку вирішує CI/CD¶
Уяви ситуацію. Ти написав функцію create_note_for_user. Вона пройшла локальні тести. Ти зробив git push. Через дві години виявляється, що форма на сторінці реєстрації більше не зберігає дані.
Як таке відбувається? Ти не торкався форми. Але десь зміна у сервісному шарі потягла за собою залежність, яку ти не бачив.
Без автоматизації цей ланцюжок виглядає так:
Розробник A Розробник B Деплой у production
пише фічу ─────┐ пише фічу ─────┐
│ │
└── merge вручну ───┴── тести вручну ── деплой вручну
(merge conflicts!) (хтось забув) (2+ год. ритуалів)
А потім у production — баг. І ніхто точно не знає, чия зміна його спричинила.
CI/CD вирішує саме це: кожен git push автоматично запускає повний набір тестів на чистому сервері. Якщо тести пройшли — код безпечний для злиття. Якщо впали — розробник бачить це ще до того, як код потрапить до main.
2. Що таке CI/CD¶
CI/CD розшифровується як Continuous Integration / Continuous Delivery (або Deployment).
Це не один інструмент і не одна кнопка. Це спосіб організувати роботу команди так, щоб тестування і деплой відбувалися автоматично після кожної зміни.
Коротко:
| Скорочення | Назва | Що робить |
|---|---|---|
| CI | Continuous Integration | Автоматично збирає і тестує код після кожного push |
| CD | Continuous Delivery | Автоматично готує білд до production — але деплоїть людина |
| CD | Continuous Deployment | Автоматично деплоїть у production без участі людини |
Різниця між Delivery і Deployment в одному слові: людина. У Delivery людина натискає кнопку підтвердження. У Deployment — ні.
Важлива думка:
CI/CD — це не про інструменти. Це про те, що тести запускаються автоматично і що feedback приходить швидко.
3. Continuous Integration vs Continuous Delivery vs Continuous Deployment¶
Розгорнута схема:
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 -- так --> F[Notify: OK]
E -- ні --> 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 -- так --> L[Людина підтверджує]
L --> M[Deploy: Production]
K -- ні --> N[Rollback Staging]
end
subgraph DEPLOYMENT["Continuous Deployment"]
direction LR
O[Artifact ready] --> P[Deploy: Staging]
P --> Q[Automated Tests]
Q --> R{OK?}
R -- так --> S[Auto Deploy: Production]
R -- ні --> 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;
Де зараз наш notes_chat_app? На рівні CI: кожен push до main запускає тести. Деплой ще не автоматизований — але це перший і найважливіший крок.
4. Компоненти GitHub Actions¶
GitHub Actions — це платформа CI/CD, вбудована прямо в GitHub. Не потрібно сторонніх сервісів.
Ієрархія компонентів:
Репозиторій
└── .github/
└── workflows/
└── django-tests.yml ← Workflow
│
├── on: push ← Event (тригер)
│
└── 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
| Компонент | Що це | Аналогія |
|---|---|---|
| Workflow | Весь сценарій у YAML файлі | Сценарій вистави |
| Event | Тригер, що запускає workflow | Піднімається завіса |
| Job | Набір кроків на одному runner | Акт вистави |
| Step | Одна команда або action | Окрема сцена |
| Action | Готовий переиспользований крок | Реквізит з магазину |
| Runner | Сервер де виконується код | Майданчик |
5. Як читати YAML workflow¶
Workflow — це YAML файл. Ось мінімальний приклад з поясненням:
name: Django Tests # Назва (відображається в GitHub → Actions)
on: # Коли запускати
push:
branches: [main] # При push у main
jobs: # Що робити
test: # Назва job
runs-on: ubuntu-latest # На якій ОС
steps: # Кроки по порядку
- uses: actions/checkout@v4 # Клонувати репозиторій
- uses: actions/setup-python@v5 # Встановити Python
with:
python-version: "3.12"
- run: pip install -r requirements.txt # Shell команда
- run: python manage.py test # Запустити тести
Правила читання:
- uses: — взяти готовий action (з marketplace)
- run: — виконати shell команду
- with: — параметри для action
- needs: — цей job чекає іншого
- env: — змінні середовища
6. Наш django-tests.yml — рядок за рядком¶
У нашому проєкті вже є workflow:
Зверни увагу: Django-проєкт (manage.py, requirements.txt) лежить прямо в корені репозиторію, тому й workflow лежить у кореневій .github/workflows/, і GitHub запускає його автоматично. Workflow, покладений у будь-яку іншу теку (наприклад, усередині docs/), GitHub ігнорує. Правильне місце завжди одне:
Розберемо його по частинах.
Тригери¶
on:
push:
branches: [ main, master ] # push у main або master
pull_request:
branches: [ main, master ] # PR до main або master
workflow_dispatch: # ручний запуск через кнопку в UI
У реальному файлі push і pull_request мають ще фільтр paths: (notes_app/**, notes_project/**, templates/**, static/**, requirements.txt і сам workflow): зміни лише в документації тести не запускають.
Що відбувається: якщо хтось відкриває Pull Request до main → GitHub побачить on: pull_request → запустить workflow → результат (зелений/червоний) з'явиться прямо у PR.
Job 1: Unit + Integration тести¶
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 (pg_isready)
env:
DATABASE_URL: postgres://notes_user:notes_pass@localhost:5432/notes_db
ubuntu-latest — це свіжа VM на Azure, яка знищується після кожного запуску. Немає стану між запусками.
services.db — контейнер PostgreSQL поруч із runner: проєкт працює тільки з PostgreSQL, тому тести отримують базу через DATABASE_URL.
Перший крок завжди однаковий: клонувати репозиторій на VM. Без цього кроку на runner-і взагалі немає твого коду.
- name: Cache pip dependencies
uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
Кеш pip залежностей. Якщо requirements.txt не змінився — pip пакети завантажаться з кешу замість інтернету. Прискорює pipeline з 3 хвилин до 1 хвилини.
manage.py check — вбудована Django команда. Перевіряє конфігурацію, моделі, middleware без запуску сервера. Якщо у тебе помилка у settings.py — дізнаєшся ще до запуску тестів.
- 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
Запускає всі тести крім Selenium (вони в окремому job), зокрема WebSocket-тести test_consumers. Параметр -v 2 — verbose, показує назву кожного тесту.
- name: Generate coverage report
run: |
coverage run manage.py test ...
coverage report --show-missing
coverage xml -o coverage.xml
Coverage: запускає тести через coverage run, щоб відстежити які рядки коду виконувались. coverage xml генерує файл для інтеграції з такими сервісами як Codecov.
- name: Upload coverage report
uses: actions/upload-artifact@v4
with:
name: coverage-xml
path: coverage.xml
Зберігає coverage.xml як артефакт — файл, який можна завантажити після завершення workflow через GitHub UI.
Job 2: Selenium E2E¶
selenium-e2e:
name: Selenium E2E Tests
needs: unit-and-integration # Запускати ПІСЛЯ успіху job "unit-and-integration"
runs-on: ubuntu-latest
services:
db:
image: postgres:16-alpine
# ... так само, як у Job 1
selenium:
image: selenium/standalone-chrome:latest
ports:
- 4444:4444
options: >-
--add-host=host.docker.internal:host-gateway
--shm-size=2gb
# ... опції health-check
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 — це Docker контейнери, які запускаються поруч із runner. Selenium/standalone-chrome запускає Chrome у безголовому режимі. Наш тест підключається до нього через http://localhost:4444. --add-host=host.docker.internal:host-gateway разом із WEB_HOST=host.docker.internal дає Chrome у контейнері змогу відкрити Django test server, що працює на 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 — змінна середовища, яку читає _make_headless_driver() у notes_app/tests/test_selenium.py. WEB_HOST читає _DockerLiveServerMixin: прив'язує test server до 0.0.0.0 і підставляє host.docker.internal у live_server_url. Якщо вона є — Selenium підключається до Remote WebDriver замість локального браузера.
7. Events — коли запускати¶
Найчастіше використовувані тригери:
on:
# При push у певні гілки
push:
branches: [main, develop]
paths: ['notes_app/**', 'tests/**'] # Тільки якщо ці файли змінились
# При відкритті або оновленні PR
pull_request:
types: [opened, synchronize, reopened]
# За розкладом (cron-синтаксис)
schedule:
- cron: '0 6 * * 1' # Щопонеділка о 6:00 UTC
# Ручний запуск через GitHub UI
workflow_dispatch:
# При публікації релізу
release:
types: [published]
Практична порада: для навчального проєкту достатньо push і pull_request. schedule корисний для нічних повних тест-ранів, release — для деплою при публікації версії.
8. Jobs і Steps — що і як виконується¶
Паралельність і залежності¶
За замовчуванням jobs виконуються паралельно. needs змінює це:
jobs:
lint: # Запускається одразу
...
test: # Запускається одразу (паралельно з lint)
...
test-selenium:
needs: test # Чекає test
...
deploy:
needs: [lint, test] # Чекає ОБОХ
...
Як це виглядає по часу:
Час: 0s 30s 60s 90s
│ │ │ │
lint ├───────────┤
test ├───────────────────────┤
selenium ├───────────┤
deploy (не запустить поки не пройдуть lint і test)
Умовне виконання¶
steps:
- name: Deploy (тільки при успіху)
if: success()
run: ./deploy.sh
- name: Сповістити про помилку (при будь-якій)
if: failure()
run: ./notify.sh
- name: Очистити temp файли (завжди)
if: always()
run: rm -rf /tmp/test_*
- name: Деплоїти тільки з main
if: github.ref == 'refs/heads/main'
run: ./deploy.sh
9. Actions — готові блоки¶
Actions — це перевикористані кроки з GitHub Marketplace.
Найчастіше використовувані у Django проєктах¶
# Клонування репозиторію (завжди перший крок)
- uses: actions/checkout@v4
# Встановлення Python з кешом pip
- uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: 'pip' # Автоматично кешує pip
# Ручний кеш (більше контролю)
- uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
# Зберегти файл як артефакт
- uses: actions/upload-artifact@v4
with:
name: test-results
path: coverage.xml
retention-days: 7 # Зберігати 7 днів
# Завантажити артефакт в іншому job
- uses: actions/download-artifact@v4
with:
name: test-results
Передача даних між Jobs¶
Jobs не мають спільної файлової системи. Для передачі даних: артефакти або 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 — де виконується код¶
GitHub-hosted runners¶
| Runner | ОС | 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 |
Для Django проєктів завжди ubuntu-latest — найшвидший і найдешевший.
Що відбувається коли ти робиш 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 (або ❌ Failed)
GH->>VM: Terminate VM (ephemeral!)
Note over VM: VM знищується. Наступний push — нова чиста VM.
Важлива деталь: VM ephemeral — знищується після кожного запуску. Немає ніякого "стану" між запусками. Якщо тести проходять на runner — вони проходять на чистій машині без твоїх локальних налаштувань.
11. Як переглянути результати в GitHub¶
- Відкрий репозиторій на GitHub
- Вкладка Actions — список всіх workflow runs
- Клікни на конкретний run — побачиш граф jobs
- Клікни на job — побачиш список steps
- Клікни на step — побачиш live logs
Що означають кольори¶
| Колір | Значення |
|---|---|
| Зелений ✅ | Step/Job завершився успішно |
| Жовтий 🟡 | Step/Job виконується прямо зараз |
| Червоний ❌ | Step/Job провалився |
| Сірий ⏭ | Step/Job пропущений (через if: або needs:) |
Live logs — твій найкращий інструмент дебагінгу¶
Кожен step розгортається у повний лог з: - Timestamp кожного рядка - Stdout і stderr процесу - Кнопка "Download log archive"
Якщо тест впав — розгорни step з тестами і читай вивід так само, як читаєш його локально.
12. CI/CD і піраміда тестування¶
Пам'ятаєш піраміду з розділу «Піраміда тестування»?
У CI/CD кожен рівень відповідає за свою роль:
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;
Чому важливий порядок? Lint падає за 30 секунд. Якщо є проблема з форматуванням — ти дізнаєшся ще до того як витратиш 5 хвилин на повний run. "Fail fast" — принцип хорошого CI.
13. GitHub Pages — публікація статичного сайту¶
GitHub Pages — вбудований спосіб публікувати статичний сайт прямо з репозиторію. Для Django документації або landing page.
Спосіб 1: Публікація з гілки (простий)¶
Поклади HTML/CSS у папку docs/ → пуш → сайт доступний за адресою username.github.io/repo.
Спосіб 2: Через GitHub Actions (гнучкий)¶
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
Важливі обмеження¶
⚠️ Сайт ПУБЛІЧНО доступний в інтернеті — навіть якщо репозиторій приватний.
⚠️ CNAME файл у репозиторії НЕ налаштовує custom domain.
Домен змінюється тільки через Settings → Pages.
ℹ️ Push через GITHUB_TOKEN не тригерить Pages rebuild
(захист від нескінченної рекурсії).
14. Типові помилки та як їх читати¶
Workflow не запускається¶
Симптом: push зроблено, але в Actions tab немає нового run
Причини:
- YAML файл не в <repo-root>/.github/workflows/ (наприклад, лежить у docs/)
- Синтаксична помилка у YAML (перевір відступи)
- Гілка не відповідає фільтру у on.push.branches
Діагностика: GitHub → Actions → "Check workflows" або дивись червону іконку
біля коміту в списку комітів
Process completed with exit code 1¶
Симптом: Step "Run unit tests" червоний, у лозі:
FAIL: test_login_required (notes_app.tests.test_views.NoteListViewTest.test_login_required)
Причина: Тест впав. Це нормально — для цього і є CI.
Дія: Розгорни step → читай traceback → виправ код або тест
Permission denied / Resource not accessible¶
Симптом: Step "Upload artifact" або "Deploy Pages" червоний
Причина: У workflow немає потрібних прав
Рішення: Додай у верхній рівень YAML:
permissions:
contents: read
pages: write
id-token: write
Cache miss кожного разу¶
Симптом: pip install займає 3 хвилини при кожному run
Причина: cache key змінюється — можливо hashFiles бере неправильний файл
Рішення: Перевір шлях:
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
↑ glob шукає requirements.txt
у будь-якій підпапці
Секрет не передано в середовище¶
Симптом: Step падає з "API key not found" або "env var is None"
Причина: Секрет є в Settings, але не передано у workflow
Рішення:
- name: Deploy
env:
API_KEY: ${{ secrets.MY_API_KEY }} ← явно передати
run: ./deploy.sh
15. Питання для самоперевірки¶
- Чим CI відрізняється від Continuous Delivery і Continuous Deployment?
- Чому runner VM знищується після кожного run — це перевага чи обмеження?
- Навіщо
actions/checkout@v4має бути першим кроком? - Чому
needs: unit-and-integrationуselenium-e2e— це важливо? - Що відбудеться якщо
on: pushвказати безbranches: [main]? - Навіщо кешувати pip залежності, якщо можна просто встановлювати кожного разу?
- Де знаходиться наш
django-tests.ymlі чому GitHub запускає його автоматично? - Яку роль відіграє
SELENIUM_REMOTE_URLу Job 2 і де цю змінну читає код тестів? - Чому lint виконується першим у pipeline, а Selenium останнім?
- Якщо тест падає в CI але проходить локально — що варто перевірити першим?