CI/CD

This document describes the continuous integration and delivery pipeline for villa-backend-sdk.

Pipeline overview

         push / pull_request
                 │
    ┌────────────┼────────────┐
    │            │            │
    ▼            ▼            ▼
  Lint        Unit         Integration
 (ruff)    (py 3.10–3.12)   (py 3.12)
    │            │            │
    └────────────┼────────────┘
                 ▼
              Build
   (full suite + coverage ≥80% + wheel)
                 │
                 ▼
           CI Success

All jobs run **in parallel** except build, which waits for lint, unit, and integration to pass first.

Workflows

Workflow	Trigger	Purpose
`.github/workflows/ci.yml`	Push, PR	Lint, test, coverage gate, build
`.github/workflows/publish.yml`	Release, manual	Test gate then PyPI publish

Job details

Lint

**Ruff check** — import order, bug patterns, Python upgrade rules

**Ruff format check** — enforces consistent formatting (no auto-commit)

Run locally:

pip install ruff
ruff check villa_backend_sdk tests
ruff format --check villa_backend_sdk tests

Unit tests

Marker: -m unit

Matrix: Python **3.10, 3.11, 3.12**

Fast, isolated tests with mocked HTTP/Cognito collaborators

pytest tests/unit -m unit -v

Integration tests

Marker: -m integration

Python 3.12

Multi-module flows with **wire-level** HTTP mocking (responses) and **AWS mocking** (moto)

pytest tests/integration -m integration -v

Integration tests are split by technique:

File	Technique	What it proves
`test_http_integration.py`	`responses`	Real `requests` stack hits mocked backend URLs
`test_cognito_integration.py`	`moto`	Real `boto3` Cognito auth against emulated user pool
`test_checkout_flow.py`	Composed mocks	Business flows (validate → pay, auth → order GET)

Build (quality gate)

Runs only after lint + unit + integration pass:

1. Full test suite with **≥80% coverage** (--cov-fail-under=80)

2. Uploads coverage.xml artifact

3. Builds sdist + wheel

4. Verifies villa --version CLI entry point

5. Verifies wheel installs and imports cleanly

pytest --cov=villa_backend_sdk --cov-fail-under=80
python -m build

Publish pipeline

Publishing to PyPI is **gated by tests**:

1. test job — runs unit + integration + coverage gate

2. publish job — builds and uploads (only if tests pass)

Trigger via GitHub Release or workflow_dispatch.

Required GitHub environment: pypi (configure PyPI trusted publishing).

Best practices enforced

Practice	How
Fail fast on lint	Separate lint job, no formatting drift
Multi-version testing	Unit matrix on 3.10–3.12
Test layering	Unit vs integration markers, separate jobs
No live API calls	`responses` + `moto` in CI
Coverage gate	80% minimum on full suite
Concurrency control	Cancel stale runs on same branch
pip caching	Faster CI via `cache: pip`
Publish gate	PyPI only after tests pass
Package smoke test	Wheel install + import in build job

Local parity with CI

Run the same checks CI runs before pushing:

pip install -e ".[dev]"

# Lint
ruff check villa_backend_sdk tests
ruff format --check villa_backend_sdk tests

# Tests
pytest tests/unit -m unit -v
pytest tests/integration -m integration -v
pytest --cov=villa_backend_sdk --cov-fail-under=80

# Package
python -m build
villa --version

Documentation deployment

The user manual is built from docs/*.md and deployed to S3 on every push to main that touches docs.

Item	Value
Workflow	`.github/workflows/deploy-docs.yml`
S3 bucket	`villa-market-backend-sdk-manual`
Manual URL	http://villa-market-backend-sdk-manual.s3-website-ap-southeast-1.amazonaws.com/latest/index.html
Build	`python3 scripts/build_manual_site.py`
Deploy	`python3 scripts/deploy_manual_s3.py`

Requires GitHub Actions secrets AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY with S3 write access.