Настраиваем CI/CD в GitHub для Python-проекта с нуля

• CI (Continuous Integration / Непрерывная интеграция) означает, что каждый раз, когда вы отправляете код в репозиторий, запускается сервер. Он скачивает ваши изменения, устанавливает зависимости и прогоняет тесты с линтерами. Цель — убедиться, что новый код ничего не сломал.
  
• CD (Continuous Deployment / Непрерывное развертывание) вступает в дело, когда CI отработал без ошибок. Код автоматически собирается и отправляется туда, где он должен работать — на сервер, в Docker Hub или публикуется как пакет в PyPI.

• Автоматизация рутины. Вам больше не нужно перед каждым коммитом локально запускать pytest, black, isort или flake8. Вы просто пишете код и делаете push. Остальное делает сервер.
  
• Защита стандартов кода (PEP8). В главную ветку (main/master) физически не попадет код, который не проходит проверки на стиль и качество. Это экономит часы на код-ревью — люди обсуждают архитектуру, а не отступы и длину строк.
  
• Устранение проблемы «А у меня на компьютере работает». Код тестируется в изолированном, чистом окружении. Если вы установили библиотеку локально, но забыли добавить ее в requirements.txt или pyproject.toml, пайплайн сразу упадет с ошибкой ModuleNotFoundError, и вы исправите это до того, как код попадет на продакшен.

• Работает «из коробки». Вам не нужно арендовать сервер, устанавливать раннеры и настраивать вебхуки (как в случае с Jenkins). Достаточно положить YAML-файл в директорию .github/workflows/ внутри вашего репозитория, и всё заработает само.
  
• Щедрые лимиты. GitHub дает 2000 минут серверного времени в месяц для приватных репозиториев. Для публичных open-source проектов время вообще не ограничено. Для подавляющего большинства небольших и средних проектов это полностью бесплатно.
  
• Экосистема и комьюнити. В GitHub Marketplace есть тысячи готовых экшенов (шагов). Вам не нужно писать bash-скрипты для установки Python, кэширования зависимостей или деплоя по SSH — для всего этого уже есть официальные и проверенные сообществом готовые блоки в 2-3 строчки кода.

from fastapi import FastAPI, HTTPException
app = FastAPI()
@app.get("/bmi")
def calculate_bmi(weight: float, height: float):
    if height <= 0 or weight <= 0:
        raise HTTPException(status_code=400, detail="Рост и вес должны быть больше нуля")
    bmi = weight / (height ** 2)
    return {"weight": weight, "height": height, "bmi": round(bmi, 2)}

from fastapi.testclient import TestClient
from src.main import app
client = TestClient(app)
def test_calculate_bmi_success():
    # Проверяем расчет для человека весом 70 кг и ростом 1.75 м
    response = client.get("/bmi?weight=70&height=1.75")
    assert response.status_code == 200
    assert response.json()["bmi"] == 22.86

bmi_project/
├── requirements.txt       # Здесь записаны fastapi, uvicorn, pytest, httpx и ruff
├── src/
│   ├── __init__.py
│   └── main.py            # Наш API
└── tests/
    ├── __init__.py
    └── test_main.py       # Наши тесты

• Обновляете зависимости (вдруг коллега добавил новую библиотеку):

pip install -r requirements.txt

• Запускаете линтер (в нашем случае ruff), чтобы проверить код на чистоту и соответствие PEP8:

ruff check .

• Прогоняете тесты, чтобы убедиться, что логика не сломалась:

pytest

name: API CI/CD
# 1. Когда запускать (Triggers)
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
# 2. Что именно делать (Jobs)
jobs:
  build-and-test:
    runs-on: ubuntu-latest # Выделяем виртуальный сервер на Linux
    # 3. Пошаговая инструкция (Steps)
    steps:
      - name: Скачиваем код репозитория
        uses: actions/checkout@v4
      - name: Устанавливаем Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Устанавливаем зависимости
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

• name: Имя пайплайна. Оно будет красиво отображаться в интерфейсе GitHub во вкладке «Actions».
  
• on: Это триггер. Мы говорим: «GitHub, запускай этот скрипт каждый раз, когда кто-то пушит код напрямую в ветку main или открывает в нее Pull Request».
  
• jobs: Задачи. Пока у нас одна задача, мы назвали её build-and-test.
  
• runs-on: ubuntu-latest: GitHub выделяет нам абсолютно чистую виртуальную машину на последней версии Ubuntu.
  
• steps: Самое интересное. Это последовательность шагов, которые сервер выполнит друг за другом:

• actions/checkout@v4 — готовый экшен (action). По умолчанию выделенный сервер абсолютно пустой. Этот шаг копирует ваш код из репозитория на виртуальную машину.
  
• actions/setup-python@v5 — еще один экшен. Он устанавливает нужную версию Python (в нашем случае 3.11).
  
• run — а это уже обычные консольные команды, которые мы запускаем внутри сервера. Ровно так же, как вы делали это локально: обновляем pip и устанавливаем fastapi, pytest и ruff из файла зависимостей.

- name: Проверка кода линтером (Ruff)
        run: ruff check .
      - name: Запуск автотестов (Pytest)
        run: pytest

• GitHub скачает код и установит зависимости (шаги пройдут успешно).
  
• Линтер ruff проверит синтаксис (тоже успешно, синтаксических ошибок в неверной формуле нет).
  
• Очередь дойдет до pytest. Наш тест ожидает индекс 22.86, а получит 40.0. Тест упадет.

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"] # Указываем нужные версии

steps:
      - name: Скачиваем код
        uses: actions/checkout@v4
      - name: Устанавливаем Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip' # <-- Включаем магию кэширования

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - name: Скачиваем код репозитория
        uses: actions/checkout@v4
      - name: Устанавливаем Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
      - name: Устанавливаем зависимости
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Проверка кода линтером (Ruff)
        run: ruff check .
      - name: Запуск автотестов (Pytest)
        run: pytest

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY ./src ./src
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

• Зайдите на страницу вашего репозитория в GitHub.
  
• Перейдите во вкладку Settings -> слева в меню Secrets and variables -> Actions.
  
• Нажмите зеленую кнопку New repository secret.
  
• Создайте два секрета:

• Name: DOCKER_USERNAME | Secret: ваш логин на Docker Hub.
  
• Name: DOCKER_TOKEN | Secret: ваш Access Token (лучше выпустить токен в настройках Docker Hub, а не использовать основной пароль от аккаунта).

on:
  push:
    branches: [ "main" ]
    tags: [ "v*.*.*" ] # Запускать и при создании тегов вида v1.0.0
  pull_request:
    branches: [ "main" ]

# ... здесь заканчивается наша предыдущая задача build-and-test ...
  build-and-push:
    # Запускаем эту задачу ТОЛЬКО если build-and-test завершилась успешно
    needs: build-and-test
    # Запускаем ТОЛЬКО если пуш содержит тег (а не просто коммит в main)
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - name: Скачиваем код
        uses: actions/checkout@v4
      # Авторизуемся в Docker Hub с помощью наших спрятанных секретов
      - name: Логин в Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}
      # Вытаскиваем версию из Git-тега (например, 1.0.0), чтобы назвать так образ
      - name: Получаем версию релиза (тег)
        id: get_version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV
      # Собираем и пушим Docker-образ
      - name: Сборка и отправка Docker-образа
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/bmi-api:latest
            ${{ secrets.DOCKER_USERNAME }}/bmi-api:${{ env.VERSION }}

• Вы работаете локально, пишите код.
  
• Делаете git push. GitHub запускает только первую часть (build-and-test). Линтеры проверили код, тесты прогнались. CD-задача игнорируется, так как это не релиз.
  
• Вы понимаете, что накопили достаточно фич для новой версии. В терминале вы создаете тег: git tag v1.0.0 и отправляете его на сервер: git push origin v1.0.0.
  
• GitHub снова запускает тесты. Как только они загораются зеленым, автоматически стартует задача build-and-push.
  
• Сервер авторизуется в Docker Hub, собирает образ bmi-api и вешает на него сразу два ярлыка: latest (последняя версия) и 1.0.0 (жестко зафиксированная версия).

git add .
git commit -m "Добавил полный CI/CD пайплайн и Dockerfile"
git push

• Зайдите на GitHub во вкладку Actions.
  
• Вы увидите, что пайплайн запустился. Но запустится только задача build-and-test (сразу 3 параллельных сервера для разных версий Python).
  
• Задача build-and-push (работа с Docker) будет пропущена. Сервер проигнорирует её, потому что мы сделали просто коммит, а не релиз. Это значит, что наше условие if: startsWith(github.ref, 'refs/tags/') работает правильно!

# Создаем ярлык версии (тег)
git tag v1.0.0
# Отправляем именно этот тег на GitHub
git push origin v1.0.0

• Снова идите во вкладку Actions в GitHub.
  
• Вы увидите новый запуск пайплайна (он будет называться по имени коммита, но рядом будет значок бирки v1.0.0).
  
• Сначала снова пробегут тесты (build-and-test).
  
• Как только тесты успешно завершатся, вы увидите, что запустилась вторая задача — build-and-push.
  
• Кликните на нее, чтобы открыть логи. Вы увидите, как сервер логинится в Docker Hub, шаг за шагом выполняет инструкции из Dockerfile и отправляет слои образа в интернет.

docker run -p 8000:8000 ВАШ_ЛОГИН/bmi-api:1.0.0