graph_rag_server/.github/workflows

CI/CD Pipeline Documentation

Overview

This directory contains GitHub Actions workflows for continuous integration and continuous deployment (CI/CD) of the RAG System.

Workflows

Test Workflow (test.yml)

The main testing workflow that runs on every push and pull request to main and develop branches.

Jobs

1. Test Job

   • Runs on: Ubuntu Latest
   • Python versions: 3.11, 3.12
   • Steps:
     • Checkout code
     • Set up Python environment
     • Install dependencies
     • Run unit tests with coverage
     • Run integration tests with coverage
     • Run end-to-end tests with coverage
     • Upload coverage to Codecov
     • Upload coverage and test logs as artifacts

2. Lint Job

   • Runs code quality checks:
     • flake8: Python linting
     • black: Code formatting check
     • isort: Import sorting check
     • mypy: Static type checking

3. Security Job

   • Runs security scans:
     • safety: Checks for known security vulnerabilities in dependencies
     • bandit: Scans code for common security issues

4. Build Status Job

   • Aggregates results from all jobs
   • Fails if test job fails

Test Execution

Unit Tests

pytest tests/unit -v --cov=src --cov-report=xml --cov-report=term -m unit

Integration Tests

pytest tests/integration -v --cov=src --cov-append --cov-report=xml --cov-report=term -m integration

End-to-End Tests

pytest tests/e2e -v --cov=src --cov-append --cov-report=xml --cov-report=term -m e2e

Coverage Requirements

• Minimum Coverage: 80%
• Coverage Report: Uploaded to Codecov
• Coverage Artifacts: Stored for 30 days

Test Markers

Tests are organized using pytest markers:

• unit: Unit tests (isolated component tests)
• integration: Integration tests (component interaction tests)
• e2e: End-to-end tests (complete workflow tests)
• slow: Tests that take > 1 second
• requires_db: Tests requiring database connection
• requires_vector_db: Tests requiring vector database
• requires_external_service: Tests requiring external services
• property: Property-based tests using Hypothesis

Running Tests Locally

All Tests

pytest

Specific Test Types

# Unit tests only
pytest -m unit

# Integration tests only
pytest -m integration

# E2E tests only
pytest -m e2e

# Exclude slow tests
pytest -m "not slow"

With Coverage

# Generate HTML coverage report
pytest --cov=src --cov-report=html

# Generate terminal coverage report
pytest --cov=src --cov-report=term

# Generate XML coverage report (for CI/CD)
pytest --cov=src --cov-report=xml

Codecov Integration

Setup

1. Sign up at codecov.io
2. Add your repository
3. Get the upload token
4. Add the token as a GitHub secret:
   • Go to repository Settings → Secrets and variables → Actions
   • Add new secret: CODECOV_TOKEN

Coverage Badge

Add to your README.md:

[![codecov](https://codecov.io/gh/YOUR_USERNAME/YOUR_REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/YOUR_USERNAME/YOUR_REPO)

Artifacts

Coverage Reports

• Retention: 30 days
• Contents:
  • coverage.xml: XML coverage report
  • htmlcov/: HTML coverage report

Test Logs

• Retention: 7 days
• Contents:
  • tests/logs/pytest.log: Detailed test execution logs

Security Reports

• Retention: 30 days
• Contents:
  • bandit-report.json: Security scan results

Troubleshooting

Tests Failing Locally but Passing in CI

1. Check Python version compatibility
2. Ensure all dependencies are installed
3. Check for environment-specific issues
4. Review test logs in artifacts

Coverage Not Uploading to Codecov

1. Verify CODECOV_TOKEN is set correctly
2. Check if coverage.xml is generated
3. Review Codecov upload logs in workflow

Slow Test Execution

1. Use test markers to run specific test suites
2. Consider parallel test execution with pytest-xdist
3. Review and optimize slow tests

Best Practices

1. Write Fast Tests: Keep unit tests under 100ms
2. Use Markers: Tag tests appropriately for selective execution
3. Mock External Dependencies: Use mocks for external services in unit tests
4. Maintain Coverage: Keep coverage above 80%
5. Review Artifacts: Check test logs and coverage reports regularly
6. Fix Failing Tests Immediately: Don't let broken tests accumulate

Future Enhancements

• Add deployment workflow
• Add performance benchmarking
• Add Docker image building
• Add automated dependency updates
• Add release automation
• Add notification integration (Slack, Discord)
• Add parallel test execution
• Add test result visualization

References

• GitHub Actions Documentation
• pytest Documentation
• Codecov Documentation
• Coverage.py Documentation