GitHub Actions Workflows for UTF Strings

This directory contains comprehensive CI/CD workflows for the UTF Strings C++23 library, ensuring cross-platform compatibility, security, and performance.

📝 Note: As of November 2025, the standalone cppcheck-analysis.yml and semgrep-security.yml workflows have been consolidated into the comprehensive sast-scanning.yml workflow for better reliability and unified security reporting.

Workflow Overview

🔄 ci.yml - Main CI/CD Pipeline

Triggers: Push, Pull Request, Release Purpose: Primary continuous integration pipeline

Jobs:

• Linux GCC 13 (x64): Debug + Release builds, tests, benchmarks
• Linux Clang 18 (x64): Debug + Release builds, tests, benchmarks
• Windows MSVC 2022 & Clang-CL (x64): Debug + Release builds, tests, benchmarks
• Linux Fuzz Testing: libFuzzer with all UTF encodings (UTF-8/16/32 BE/LE)
• Linux Sanitizers: AddressSanitizer + ThreadSanitizer (GCC & Clang)
• Windows Sanitizers: AddressSanitizer (MSVC & Clang-CL)
• Performance Tracking: Baseline performance monitoring
• Test Results Publishing: Unified test result reporting
• Documentation Artifacts: Generates combined docs for GitHub Pages

Features:

• ✅ Cross-platform builds (Linux GCC/Clang, Windows MSVC/Clang-CL)
• ✅ Comprehensive testing (unit tests, fuzz tests, sanitizers)
• ✅ Performance benchmarking with tracking
• ✅ Code formatting validation (clang-format)
• ✅ Artifact collection and reporting

�️ sast-scanning.yml - Comprehensive SAST Security Scanning

Triggers: Push, Pull Request, Daily Schedule (4 AM UTC), Manual Dispatch Purpose: Comprehensive Static Application Security Testing (SAST) with multiple security tools

Jobs:

• Trivy Scan: Vulnerability and misconfiguration detection
• Checkov Scan: Infrastructure as Code security analysis
• Gitleaks Scan: Secret detection in git history
• Cppcheck Analysis: C/C++ static code analysis
• Semgrep Analysis: Security pattern matching and vulnerability detection
• SAST Summary: Comprehensive reporting and artifact management

Features:

• ✅ Integrated security tools - All tools run directly in one workflow
• ✅ Configurable scan intensity - Basic, Comprehensive, Deep scanning levels
• ✅ SARIF integration - All results uploaded to GitHub Security/Code Scanning tab
• ✅ No external dependencies - No PAT tokens or workflow dispatch permissions needed
• ✅ Comprehensive reporting - Unified summary with detailed artifact management
• ✅ PR integration - Automatic security scan results in pull request comments

Security Tools Coverage:

• Trivy (trivy-security): Container vulnerabilities, OS packages, misconfigurations
• Checkov (checkov-infrastructure): GitHub Actions, Dockerfile, YAML/JSON security
• Gitleaks (gitleaks-secrets): Full git history secret detection
• Cppcheck (cppcheck-static-analysis): C++ static analysis with configurable severity
• Semgrep (semgrep-security): Security patterns and vulnerability detection

Scan Intensity Levels:

• Basic: Error-level issues only (fast)
• Comprehensive (default): Warning + error issues (balanced)
• Deep: All issue types including style and performance (thorough)

�🔒 codeql.yml - Advanced Security Analysis

Triggers: Push, Pull Request, Release, Weekly Schedule Purpose: Advanced semantic security analysis using GitHub CodeQL

Jobs:

• CodeQL Analysis: Linux x64 Clang Release build analysis
• Enhanced Security Analysis: Additional security tools for releases

Features:

• ✅ CodeQL scanning with security-extended queries
• ✅ Release security validation (clang-tidy, valgrind)
• ✅ Custom query configuration for C++ security patterns
• ✅ Binary security analysis (stack protection, ASLR, PIE, NX bit)
• ✅ SARIF results uploaded to GitHub Security tab

Security Checks:

• Buffer overflow detection (CWE-119, CWE-120)
• Integer overflow detection (CWE-190)
• Use-after-free detection (CWE-416)
• Out-of-bounds access (CWE-787, CWE-788)

📄 pages-deploy.yml - GitHub Pages Deployment

Triggers: CI Workflow Completion, Manual Dispatch Purpose: Dedicated GitHub Pages deployment with explicit Jekyll disable

Jobs:

• Deploy Documentation: Deploys combined documentation to GitHub Pages

Features:

• ✅ Isolated deployment - Separate from main CI for reliability
• ✅ Jekyll disabled - Explicit .nojekyll file creation and Jekyll file cleanup
• ✅ Artifact management - Downloads docs from CI workflow completion
• ✅ Static site optimization - Removes Jekyll conflicts and sets proper permissions
• ✅ Deployment verification - Comprehensive validation and reporting

🏷️ create-release.yml - Automated Release Creation

Triggers: Version Tags (v*.*.*), Manual Dispatch with Version Input Purpose: Automated GitHub release creation with cross-platform binary distribution

Jobs:

• Build Release Binaries: Multi-platform builds for Linux and Windows
• Create GitHub Release: Automated release with downloadable assets

Platform Matrix:

• Linux GCC 13 (x64): Release + Debug binaries (.tar.gz)
• Linux Clang 18 (x64): Release + Debug binaries (.tar.gz)
• Windows MSVC 2022 (x64): Release + Debug binaries (.zip)
• Windows Clang (x64): Release + Debug binaries (.zip)

Features:

• ✅ Semantic versioning - Supports v0.0.1, v1.2.3 format tags
• ✅ Dual build types - Both optimized Release and Debug binaries
• ✅ Complete packaging - Binaries, headers, static libraries, documentation
• ✅ Platform-specific archives - .tar.gz for Linux, .zip for Windows
• ✅ Binary validation - Tests run before packaging to ensure functionality
• ✅ Professional release notes - Auto-generated changelog with asset descriptions
• ✅ Manual trigger support - Can create releases via workflow dispatch

Release Assets Structure:

utf_strings-v{version}-{Platform}/
├── VERSION.txt                    # Release metadata
├── utf_strings-tests-release      # Optimized test executable
├── utf_strings-tests-debug        # Debug test executable
├── utf_strings-bench-release      # Optimized benchmark executable  
├── utf_strings-bench-debug        # Debug benchmark executable
├── include/utf/                   # Complete header files
│   ├── utf_codepoints.hpp
│   └── version.hpp
├── *.a/*.lib                      # Static libraries
├── LICENSE                        # License file
└── README.md                      # Documentation

Usage Examples:

# Automatic trigger via tag
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

# Manual trigger via GitHub CLI
gh workflow run create-release.yml -f version=0.1.0 -f create_tag=true

# Manual trigger via GitHub UI
# Actions tab → Create Release → Run workflow → Enter version

🧪 extended-fuzz.yml - Extended Fuzz Testing

Triggers: Daily Schedule (2 AM UTC), Manual Dispatch Purpose: Long-running fuzz testing for thorough security validation

Jobs:

• Extended Fuzz Testing: 1+ hour fuzzing sessions for all UTF encodings

Features:

• ✅ Configurable duration (default 1 hour, manual override)
• ✅ Comprehensive coverage (UTF-8, UTF-16 BE/LE, UTF-32 BE/LE)
• ✅ Corpus management with persistent test cases
• ✅ Automatic issue creation on crash detection
• ✅ Detailed reporting with statistics and artifacts

🚀 release-validation.yml - Release Validation

Triggers: Release Published, Manual Dispatch Purpose: Comprehensive validation of release builds

Jobs:

• Cross-Platform Release Builds: Linux (GCC/Clang) + Windows (MSVC/Clang-CL)
• Security Validation: Enhanced security analysis for releases
• Release Summary: Automated release documentation

Features:

• ✅ Multi-platform validation with artifact generation
• ✅ Binary security analysis with hardening verification
• ✅ Performance validation with benchmark execution
• ✅ Automated release notes with validation status
• ✅ Release artifact packaging for distribution

Configuration Files

🔧 codeql-config.yml - CodeQL Configuration

Purpose: Custom CodeQL analysis configuration

Features:

• Security-focused query suites
• Path filtering for relevant source code
• C++-specific build configuration
• Additional security query packs

Workflow Matrix Coverage

Platform	Compiler	Debug	Release	Tests	Benchmarks	Fuzz	Sanitizers	SAST Security	CodeQL	Pages Deploy	Create Release
Linux x64	GCC 13	✅	✅	✅	✅	❌	✅	✅	✅	✅	✅
Linux x64	Clang 18	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Windows x64	MSVC 2022 & Clang	✅	✅	✅	✅	⚠️*	✅**	✅	✅	✅	✅

*Windows fuzz testing uses harnesses (no libFuzzer)
**Windows sanitizers: AddressSanitizer only
***SAST Security includes: Trivy, Checkov, Gitleaks, Cppcheck, Semgrep

Security Analysis Features

Comprehensive SAST Scanning

• Trivy: Vulnerability scanning for containers, OS packages, and misconfigurations
• Checkov: Infrastructure as Code security analysis (GitHub Actions, Docker, YAML/JSON)
• Gitleaks: Secret detection across full git history
• Cppcheck: C/C++ static analysis with configurable severity levels
• Semgrep: Security pattern matching and vulnerability detection
• CodeQL: Advanced semantic analysis with security queries
• clang-tidy: Security-focused checks (security-, cert-, bugprone-*)

Dynamic Analysis

• AddressSanitizer: Memory error detection (Linux GCC/Clang, Windows MSVC/Clang-CL)
• ThreadSanitizer: Data race detection (Linux GCC/Clang)
• UndefinedBehaviorSanitizer: Undefined behavior detection (Linux GCC/Clang)
• LeakSanitizer: Memory leak detection (Linux GCC/Clang)
• Valgrind: Memory analysis for releases (Linux)

Fuzz Testing

• libFuzzer: Comprehensive fuzzing with sanitizers (Linux Clang)
• Extended sessions: Daily 1+ hour fuzzing runs
• Multi-encoding coverage: UTF-8, UTF-16 BE/LE, UTF-32 BE/LE
• Corpus management: Persistent test case storage

Binary Security Analysis

• Stack protection: Compiler-generated stack canaries
• FORTIFY_SOURCE: Buffer overflow protection
• PIE/ASLR: Address space layout randomization
• NX bit: Non-executable stack protection

Performance Monitoring

Benchmark Tracking

• Google Benchmark: Performance measurement framework
• Baseline tracking: Automated performance regression detection
• Alert system: 150% threshold for performance degradation
• Cross-platform comparison: Performance across different compilers

Optimization Validation

• Release builds: Aggressive optimization verification (-O3, /O2)
• LTO verification: Link-time optimization effectiveness
• Native CPU optimization: Platform-specific instruction usage

Artifact Management

Build Artifacts

• Binaries: Tests and benchmark executables
• Libraries: Static and shared libraries (.a, .so, .lib, .dll)
• Headers: Complete include directory structure
• Test results: XML format for reporting integration

Security Artifacts

• SARIF files: Security analysis results
• Crash dumps: Fuzz testing failures
• Analysis reports: clang-tidy, cppcheck, valgrind outputs
• Binary analysis: Security feature verification

Performance Artifacts

• Benchmark results: JSON format with timing data
• Performance baselines: Historical performance tracking
• Regression reports: Performance change analysis

Integration Points

External Services

• GitHub Security: CodeQL SARIF upload, security advisories
• GitHub Releases: Automated validation and documentation
• Artifact storage: GitHub Actions artifact system
• Issue tracking: Automated issue creation on failures

Notification System

• PR comments: Test results and performance impact
• Release updates: Automated release notes with validation status
• Alert system: Performance regression and security issue alerts
• Email notifications: Critical failure notifications

Usage Examples

Running Workflows

# Create a new release (recommended approach)
git tag -a v0.1.0 -m "Release v0.1.0 - New features and improvements"
git push origin v0.1.0

# Create release manually via GitHub CLI
gh workflow run create-release.yml -f version=0.1.0 -f create_tag=true

# Trigger extended fuzz testing manually (2 hours)
gh workflow run extended-fuzz.yml -f duration=7200

# Validate a specific release
gh workflow run release-validation.yml -f release_tag=v1.0.0

# Check workflow status
gh run list --workflow=ci.yml

# Monitor release creation
gh run list --workflow=create-release.yml

Local Testing

# Reproduce CI builds locally
./bootstrap_cmake.sh --compiler gcc --config Release
./bootstrap_cmake.sh --compiler clang --config Debug --enable-fuzz

# Run security analysis locally
cmake --build --preset conan-release --target format-check
clang-tidy src/*.cpp include/*.hpp -- -std=c++23

This comprehensive CI/CD system ensures the UTF Strings library maintains high quality, security, and performance standards across all supported platforms! 🚀