0x524a
00e2e0d46f
- Enhanced .golangci.yml with additional linters and settings for improved code quality checks. - Updated CI workflow to include multiple branches for pull requests and improved caching strategies. - Added new workflows for documentation checks, dependency reviews, and security scans. - Refined coverage analysis workflow to provide detailed reports and comments on pull requests. - Removed outdated test workflow and consolidated testing strategies into extended tests. - Improved release workflow with better version handling and artifact management.
191 lines
4.9 KiB
Markdown
191 lines
4.9 KiB
Markdown
# CI/CD Documentation
|
|
|
|
## Overview
|
|
|
|
The ONVIF Go library uses GitHub Actions for continuous integration and deployment. All workflows are located in `.github/workflows/`.
|
|
|
|
## Workflow Summary
|
|
|
|
| Workflow | Purpose | Triggers | Status |
|
|
|----------|---------|----------|--------|
|
|
| **CI** | Main CI pipeline | Push/PR to main branches | ✅ Active |
|
|
| **Test** | Extended testing | Manual/Weekly/Code changes | ✅ Active |
|
|
| **Coverage** | Coverage analysis | After CI success | ✅ Active |
|
|
| **Release** | Create releases | Tags/Manual | ✅ Active |
|
|
| **Lint** | Code linting | Push/PR | ✅ Active |
|
|
| **Security** | Security scanning | Push/PR/Weekly | ✅ Active |
|
|
| **Docs** | Documentation checks | Docs changes | ✅ Active |
|
|
| **Dependency Review** | Dependency security | PRs | ✅ Active |
|
|
|
|
## Main CI Workflow
|
|
|
|
The **CI** workflow (`ci.yml`) is the primary workflow that runs on every push and pull request.
|
|
|
|
### Jobs
|
|
|
|
1. **validate** - Quick validation (5-10 minutes)
|
|
- Code formatting check
|
|
- `go vet`
|
|
- Linting with golangci-lint
|
|
|
|
2. **test** - Primary testing (10-15 minutes)
|
|
- Runs on Go 1.23
|
|
- Race detector enabled
|
|
- Coverage report generation
|
|
- Uploads to Codecov
|
|
|
|
3. **test-matrix** - Multi-platform testing (20-30 minutes)
|
|
- Tests on Go 1.21, 1.22, 1.23
|
|
- Tests on Linux, macOS, Windows
|
|
- Parallel execution
|
|
|
|
4. **build** - Build verification (5-10 minutes)
|
|
- Builds all packages
|
|
- Builds all examples
|
|
- Builds all CLI tools
|
|
|
|
5. **sonarcloud** - Code quality (10-15 minutes)
|
|
- Only on master/main
|
|
- Requires SONAR_TOKEN secret
|
|
|
|
### Performance
|
|
|
|
- **Total CI time**: ~40-60 minutes (parallel jobs)
|
|
- **Fast feedback**: Validation job fails fast on formatting/lint issues
|
|
- **Caching**: Go modules and build cache for faster runs
|
|
|
|
## Release Workflow
|
|
|
|
The **Release** workflow (`release.yml`) creates GitHub releases with binaries for all platforms.
|
|
|
|
### Supported Platforms
|
|
|
|
- **Linux**: amd64, arm64, arm (v7)
|
|
- **Windows**: amd64, arm64
|
|
- **macOS**: amd64, arm64
|
|
|
|
### Release Process
|
|
|
|
1. **Tag creation**: Push a tag like `v1.2.3`
|
|
2. **Build**: Automatically builds for all platforms
|
|
3. **Archive**: Creates `.tar.gz` (Linux/macOS) and `.zip` (Windows)
|
|
4. **Checksums**: Generates SHA256 checksums
|
|
5. **Release**: Creates GitHub release with all artifacts
|
|
6. **Docker**: Builds and pushes multi-arch Docker image to GHCR
|
|
|
|
### Manual Release
|
|
|
|
You can also trigger a release manually:
|
|
1. Go to Actions → Release workflow
|
|
2. Click "Run workflow"
|
|
3. Enter version (e.g., `v1.2.3`)
|
|
|
|
## Security Workflow
|
|
|
|
The **Security** workflow (`security.yml`) scans for vulnerabilities.
|
|
|
|
### Tools
|
|
|
|
- **gosec**: Security scanner for Go code
|
|
- **govulncheck**: Vulnerability checker for dependencies
|
|
|
|
### Schedule
|
|
|
|
Runs weekly on Sundays to catch new vulnerabilities.
|
|
|
|
## Coverage
|
|
|
|
Coverage is tracked and reported to Codecov. The coverage workflow provides detailed analysis:
|
|
|
|
- Total coverage percentage
|
|
- Coverage by package
|
|
- Coverage trends over time
|
|
|
|
### Coverage Threshold
|
|
|
|
Minimum coverage threshold: **50%**
|
|
|
|
## Required Secrets
|
|
|
|
### Optional Secrets
|
|
|
|
- `CODECOV_TOKEN` - For Codecov integration
|
|
- `SONAR_TOKEN` - For SonarCloud integration
|
|
- `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` - For Docker Hub
|
|
|
|
## Workflow Status Badges
|
|
|
|
Add these badges to your README:
|
|
|
|
```markdown
|
|
|
|
|
|
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Always run CI locally first**: `make check test`
|
|
2. **Keep workflows fast**: Use caching and parallel jobs
|
|
3. **Fail fast**: Validation job catches issues early
|
|
4. **Test before release**: All tests must pass before tagging
|
|
5. **Review security scans**: Check security workflow results
|
|
|
|
## Troubleshooting
|
|
|
|
### CI Fails on Formatting
|
|
|
|
```bash
|
|
# Fix formatting
|
|
make fmt
|
|
|
|
# Or manually
|
|
gofmt -w .
|
|
```
|
|
|
|
### CI Fails on Linting
|
|
|
|
```bash
|
|
# Run linter locally
|
|
make lint
|
|
|
|
# Or manually
|
|
golangci-lint run ./...
|
|
```
|
|
|
|
### Tests Fail Locally but Pass in CI
|
|
|
|
- Check Go version: CI uses Go 1.23
|
|
- Check race detector: CI runs with `-race`
|
|
- Check environment differences
|
|
|
|
### Release Fails
|
|
|
|
- Ensure tag format: `v1.2.3` (not `1.2.3`)
|
|
- Check permissions: Need `contents: write`
|
|
- Verify all tests pass before tagging
|
|
|
|
## Workflow Files
|
|
|
|
All workflow files are in `.github/workflows/`:
|
|
|
|
- `ci.yml` - Main CI pipeline
|
|
- `test.yml` - Extended tests
|
|
- `coverage.yml` - Coverage analysis
|
|
- `release.yml` - Release automation
|
|
- `lint.yml` - Linting
|
|
- `security.yml` - Security scanning
|
|
- `docs.yml` - Documentation checks
|
|
- `dependency-review.yml` - Dependency review
|
|
|
|
## See Also
|
|
|
|
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
|
- [Workflow README](../.github/workflows/README.md)
|
|
- [Makefile](../Makefile) - Local development commands
|
|
|
|
---
|
|
|
|
*Last Updated: December 2, 2025*
|
|
|