180 lines
5.1 KiB
Markdown
180 lines
5.1 KiB
Markdown
# GitHub Actions CI/CD Setup
|
|
|
|
This repository includes a comprehensive GitHub Actions workflow for C++20 compilation, testing, and code coverage reporting.
|
|
|
|
## Features
|
|
|
|
### 🔧 Multi-Platform Build & Test
|
|
- **Ubuntu Latest**: Primary development target with GCC
|
|
- **macOS Latest**: Cross-platform compatibility with Clang
|
|
- **Windows Latest**: Broader compatibility with GCC via vcpkg
|
|
|
|
### 🧪 Comprehensive Testing
|
|
- Runs all Google Test unit tests
|
|
- Validates security features (directory traversal protection)
|
|
- Fails build on any test failures
|
|
- Uploads test logs as artifacts
|
|
|
|
### 📊 Code Coverage Reporting
|
|
- **Coverage Tool**: gcov + lcov for detailed coverage analysis
|
|
- **Integration**: Automatic upload to Codecov.io
|
|
- **Reports**: HTML coverage reports as downloadable artifacts
|
|
- **Thresholds**: Configurable coverage targets (default: 80%)
|
|
- **PR Comments**: Automatic coverage change reporting
|
|
|
|
## Workflow Structure
|
|
|
|
```
|
|
CI Workflow
|
|
├── Build & Test Matrix (Ubuntu, macOS, Windows)
|
|
│ ├── Install Dependencies (Boost, Google Test)
|
|
│ ├── Meson Setup & Configure
|
|
│ ├── Compile with C++20
|
|
│ ├── Run Unit Tests
|
|
│ └── Upload Test Artifacts
|
|
└── Coverage Analysis (Ubuntu only)
|
|
├── Build with Coverage Flags
|
|
├── Run Tests with Coverage Collection
|
|
├── Generate lcov Reports
|
|
├── Upload to Codecov
|
|
└── Generate HTML Reports
|
|
```
|
|
|
|
## Setup Instructions
|
|
|
|
### 1. Repository Setup
|
|
1. Push this repository to GitHub
|
|
2. Update the badge URLs in `README.md`:
|
|
```markdown
|
|
[](https://github.com/YOUR_USERNAME/YOUR_REPO_NAME/actions)
|
|
[](https://codecov.io/gh/YOUR_USERNAME/YOUR_REPO_NAME)
|
|
```
|
|
|
|
### 2. Codecov Integration
|
|
1. Visit [codecov.io](https://codecov.io) and sign in with GitHub
|
|
2. Add your repository to Codecov
|
|
3. No additional setup required - the workflow handles token-free uploads
|
|
|
|
### 3. Branch Protection (Optional)
|
|
Configure branch protection rules in GitHub:
|
|
- Require status checks to pass before merging
|
|
- Require branches to be up to date before merging
|
|
- Include the "Build and Test" and "Code Coverage" checks
|
|
|
|
## Configuration Files
|
|
|
|
### `.github/workflows/ci.yml`
|
|
Main CI/CD workflow with:
|
|
- Multi-platform build matrix
|
|
- Dependency management for each OS
|
|
- Test execution and artifact collection
|
|
- Coverage analysis and reporting
|
|
|
|
### `.codecov.yml`
|
|
Codecov configuration with:
|
|
- Coverage targets (80% project, 80% patch)
|
|
- File exclusions (test files, build directories)
|
|
- PR comment formatting
|
|
- Coverage flags for different components
|
|
|
|
### `.gitignore` Updates
|
|
Added coverage-related file exclusions:
|
|
- `*.gcda`, `*.gcno`, `*.gcov` - Coverage data files
|
|
- `coverage/` - Coverage report directories
|
|
- `coverage*.info` - lcov report files
|
|
|
|
## Workflow Triggers
|
|
|
|
The CI workflow runs on:
|
|
- **Push** to `main` and `develop` branches
|
|
- **Pull Requests** targeting `main` and `develop` branches
|
|
|
|
## Artifacts Generated
|
|
|
|
### Test Results
|
|
- Test logs from all platforms
|
|
- Available for 90 days after workflow completion
|
|
|
|
### Coverage Reports
|
|
- HTML coverage reports (viewable in browser)
|
|
- lcov data files for further analysis
|
|
- Codecov integration for web-based viewing
|
|
|
|
## Coverage Analysis
|
|
|
|
The coverage analysis focuses on:
|
|
- `handler.cpp` - Core business logic
|
|
- Security validation functions
|
|
- File I/O operations
|
|
- Excludes test files and system headers
|
|
|
|
### Coverage Thresholds
|
|
- **Project Coverage**: 80% minimum
|
|
- **Patch Coverage**: 80% minimum for new code
|
|
- **Threshold**: 5% tolerance for coverage changes
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Dependency Installation Failures**
|
|
- Check if package names are correct for the target OS
|
|
- Verify vcpkg installation on Windows
|
|
|
|
2. **Coverage Upload Failures**
|
|
- Coverage uploads are set to non-blocking (`fail_ci_if_error: false`)
|
|
- Check Codecov repository configuration
|
|
|
|
3. **Test Failures**
|
|
- Review test logs in the workflow artifacts
|
|
- Ensure all tests pass locally before pushing
|
|
|
|
### Local Testing
|
|
|
|
Test the workflow components locally:
|
|
|
|
```bash
|
|
# Standard build and test
|
|
meson setup builddir
|
|
meson compile -C builddir
|
|
meson test -C builddir --verbose
|
|
|
|
# Coverage build and test
|
|
meson setup builddir-coverage -Db_coverage=true
|
|
meson compile -C builddir-coverage
|
|
meson test -C builddir-coverage
|
|
```
|
|
|
|
## Customization
|
|
|
|
### Adding New Platforms
|
|
Extend the build matrix in `.github/workflows/ci.yml`:
|
|
```yaml
|
|
matrix:
|
|
os: [ubuntu-latest, macos-latest, windows-latest, ubuntu-20.04]
|
|
```
|
|
|
|
### Changing Coverage Targets
|
|
Modify `.codecov.yml`:
|
|
```yaml
|
|
coverage:
|
|
status:
|
|
project:
|
|
default:
|
|
target: 90% # Increase to 90%
|
|
```
|
|
|
|
### Adding Static Analysis
|
|
Add steps to the workflow for tools like:
|
|
- cppcheck
|
|
- clang-tidy
|
|
- AddressSanitizer/UBSan (already partially enabled)
|
|
|
|
## Security Considerations
|
|
|
|
The workflow includes security best practices:
|
|
- Pinned action versions (`@v4`, `@v3`)
|
|
- No secrets required for basic functionality
|
|
- Minimal permissions for workflow execution
|
|
- Static linking to reduce runtime dependencies
|