GitHub Actions CI/CD Documentation

This directory contains the Continuous Integration and Continuous Deployment (CI/CD) workflows for the Asset Report CLI application.

📋 Table of Contents

Overview
Workflow Structure
Naming Conventions
Jobs Description
Triggers and Conditions
Environment Configuration
Artifacts and Reports
Maintenance and Updates

🔍 Overview

The CI/CD pipeline for Asset Report CLI is designed following modern DevOps practices with a focus on:

Quality Assurance: Multi-stage testing and code quality checks
Security: Automated vulnerability scanning and security analysis
Performance: Basic performance profiling and memory usage monitoring
Deployment Readiness: Automated artifact creation and validation

🏗️ Workflow Structure

Primary Workflow: `asset-report-cli-ci.yml`

This comprehensive workflow handles the complete CI/CD pipeline for the Asset Report CLI application located in apps/asset_report_cli/.

📝 Naming Conventions

Workflow Files

Format: {application-name}-{purpose}.yml
Example: asset-report-cli-ci.yml
Purpose: Clear identification of application and workflow type

Job Names

Format: {purpose}-{type} (kebab-case)
Examples:
- code-quality - Code quality analysis
- unit-tests - Unit testing
- integration-tests - Integration testing
- security-scan - Security analysis
- build-validation - Build and documentation validation
- performance-tests - Performance testing
- deployment-check - Deployment readiness

Artifact Names

Format: {application-name}-{type}-{identifier}
Examples:
- asset-report-cli-deployment-{github.sha}
- security-reports
- test-results

Branch Strategy

main: Production-ready code, triggers full CI/CD pipeline
develop: Development branch, triggers CI pipeline
feature/*: Feature branches, triggers CI on PR to main

🔧 Jobs Description

1. Code Quality Analysis (`code-quality`)

Purpose: Ensures code meets quality standards and formatting conventions

Tools Used:

Black: Python code formatter
isort: Import statement organizer
Flake8: Python linting and style checking
Pylint: Advanced static analysis
MyPy: Static type checking

Success Criteria:

All code passes Black formatting checks
Import statements are properly organized
No critical Flake8 violations (E9, F63, F7, F82)
Pylint score above threshold
Type hints are properly defined

2. Unit Testing (`unit-tests`)

Purpose: Validates individual components functionality

Strategy:

Matrix Testing: Python versions 3.10, 3.11, 3.12
Coverage Analysis: Measures test coverage using coverage.py
Parallel Execution: Tests run across multiple Python versions simultaneously

Reports Generated:

Coverage report with missing lines
XML coverage report for external tools
JUnit-style test results

3. Integration Testing (`integration-tests`)

Purpose: Validates component interactions and CLI functionality

Scope:

End-to-end workflow testing
CLI interface validation
Template processing verification
CSV processing integration

Dependencies: Requires unit-tests to pass

4. Security & Dependency Scanning (`security-scan`)

Purpose: Identifies security vulnerabilities and dependency issues

Tools Used:

Safety: Checks Python dependencies for known vulnerabilities
Bandit: Python security linter for common security issues
Semgrep: Static analysis for security patterns

Outputs:

JSON security reports
Vulnerability summaries
Actionable security recommendations

5. Build & Documentation Validation (`build-validation`)

Purpose: Ensures application can be properly built and documented

Validations:

Python package structure verification
Import dependency resolution
README.md presence and validity
Template file existence and structure

Dependencies: Requires code-quality and unit-tests to pass

6. Performance Testing (`performance-tests`)

Purpose: Basic performance monitoring and memory profiling

Scope:

Memory usage profiling
Import time measurement
Basic performance benchmarks

Trigger: Only on main branch pushes Dependencies: Requires integration-tests to pass

7. Deployment Readiness Check (`deployment-check`)

Purpose: Final validation and artifact creation for deployment

Activities:

Comprehensive status check
Deployment package creation
Artifact uploading with versioning

Trigger: Only on main branch Dependencies: All previous jobs must pass

🎯 Triggers and Conditions

Path-Based Triggering

The workflow is optimized to run only when relevant files change:

paths:
  - 'apps/asset_report_cli/**'
  - '.github/workflows/asset-report-cli-ci.yml'

Branch-Based Conditions

Push Events: main, develop branches
Pull Request Events: Only to main branch
Conditional Jobs: Some jobs only run on specific branches

Job Dependencies

graph TD
    A[code-quality] --> D[build-validation]
    B[unit-tests] --> C[integration-tests]
    B --> D
    C --> E[performance-tests]
    A --> F[deployment-check]
    B --> F
    C --> F
    G[security-scan] --> F
    D --> F

⚙️ Environment Configuration

Python Version Strategy

Primary: Python 3.12 (latest stable)
Matrix Testing: 3.10, 3.11, 3.12 (broad compatibility)
Deployment Target: Python 3.12

Dependency Management

Core Dependencies: pandas (as specified in requirements.txt)
Development Dependencies: Installed per job requirements
Caching Strategy: pip cache with matrix-aware keys

Working Directory

All jobs operate within ./apps/asset_report_cli to maintain isolation.

📊 Artifacts and Reports

Security Reports

Location: security-reports artifact
Contents:
- safety-report.json - Dependency vulnerability scan
- bandit-report.json - Code security analysis
Retention: 90 days (default)

Test Coverage

Format: XML and console output
Integration: Codecov for external reporting
Threshold: Configurable per project needs

Deployment Package

Name: asset-report-cli-deployment-{github.sha}
Contents: Complete application with dependencies
Retention: 30 days
Format: Ready-to-deploy archive

🛠️ Maintenance and Updates

Regular Maintenance Tasks

Weekly:
- Review security scan results
- Update dependency versions if needed
- Check for GitHub Actions updates
Monthly:
- Update Python versions in matrix if new releases
- Review and update security tool versions
- Analyze performance trends
Quarterly:
- Review and update CI/CD strategy
- Evaluate new tools and integrations
- Update documentation

Version Updates

Python Versions

Update the matrix in unit-tests job when new Python versions are released:

strategy:
  matrix:
    python-version: ['3.11', '3.12', '3.13']  # Add new versions

GitHub Actions

Keep action versions updated for security and features:

- uses: actions/checkout@v4  # Update to latest
- uses: actions/setup-python@v4  # Update to latest

Security Tools

Regularly update security scanning tools:

pip install safety bandit semgrep --upgrade

Troubleshooting Common Issues

Job Failures

Code Quality Failures:
- Run black . locally to fix formatting
- Run isort . to fix import organization
- Review Flake8 and Pylint suggestions
Test Failures:
- Check test logs for specific failures
- Verify local test environment matches CI
- Review dependency compatibility
Security Scan Issues:
- Review security reports in artifacts
- Update vulnerable dependencies
- Add security exceptions if needed

Performance Issues

Slow CI Runs:
- Review caching strategy
- Optimize job dependencies
- Consider parallel execution
Resource Constraints:
- Monitor job execution times
- Optimize test data size
- Consider runner upgrades

Contributing to CI/CD

When contributing improvements to the CI/CD pipeline:

Test Changes: Test workflow changes in a fork first
Documentation: Update this README for any significant changes
Backward Compatibility: Ensure changes don't break existing functionality
Security: Review security implications of any changes

Contact and Support

For CI/CD related issues:

Create GitHub issues with ci/cd label
Include workflow run links and error logs
Tag relevant maintainers for urgent issues

Last Updated: July 16, 2025 Workflow Version: 1.0.0 Maintainer: Asset Report CLI Team

sizer/asset_report_cli