feat: Add comprehensive Gitea CI/CD workflows for multi-arch container builds
- Add build-container.yml: Main build pipeline with multi-arch support - Add pr-check.yml: Pull request validation with comprehensive testing - Add release.yml: Automated release pipeline with security scanning - Add nightly.yml: Daily builds with performance testing - Add health_check.sh: Container health validation script - Add setup-ci.sh: Local CI/CD environment setup script - Add comprehensive CI/CD documentation Features: - Multi-architecture builds (linux/amd64, linux/arm64) - Security scanning with Trivy - Automated PyPI publishing for releases - Container registry integration - Performance testing and validation - Artifact management and cleanup - Build caching and optimization Supports full development workflow from PR to production deployment.
This commit is contained in:
William Valentin
373
.gitea/workflows/README.md
Normal file
373
.gitea/workflows/README.md
Normal file
@@ -0,0 +1,373 @@
|
||||
# Gitea CI/CD Workflows
|
||||
|
||||
This directory contains the CI/CD workflows for UnitForge using Gitea Actions. These workflows automate testing, building, and deploying multi-architecture container images.
|
||||
|
||||
## Workflows Overview
|
||||
|
||||
### 1. `build-container.yml` - Main Build Pipeline
|
||||
**Triggers:** Push to `main`/`develop`, tags starting with `v*`
|
||||
|
||||
**Features:**
|
||||
- Runs comprehensive tests (linting, type checking, security)
|
||||
- Builds multi-arch container images (linux/amd64, linux/arm64)
|
||||
- Pushes to container registry
|
||||
- Security scanning with Trivy
|
||||
- Automatic deployment to staging/production
|
||||
|
||||
**Jobs:**
|
||||
- `test` - Run linting, tests, and security checks
|
||||
- `build-and-push` - Build and push multi-arch container images
|
||||
- `security-scan` - Vulnerability scanning
|
||||
- `deploy-staging` - Deploy to staging (develop branch)
|
||||
- `deploy-production` - Deploy to production (tags)
|
||||
|
||||
### 2. `pr-check.yml` - Pull Request Validation
|
||||
**Triggers:** Pull requests to `main`/`develop`
|
||||
|
||||
**Features:**
|
||||
- Full test suite including coverage reporting
|
||||
- Multi-arch build testing (no push)
|
||||
- Container startup verification
|
||||
- Configuration validation
|
||||
- PR summary with build status
|
||||
|
||||
**Jobs:**
|
||||
- `test` - Complete test suite with coverage
|
||||
- `build-test` - Test multi-arch builds without pushing
|
||||
- `validate-config` - Validate project configuration
|
||||
- `pr-summary` - Generate build status summary
|
||||
|
||||
### 3. `release.yml` - Release Pipeline
|
||||
**Triggers:** Tags matching `v*` pattern
|
||||
|
||||
**Features:**
|
||||
- Version validation and metadata extraction
|
||||
- Full test suite across all Python versions
|
||||
- Multi-arch container builds with release tags
|
||||
- Security scanning with vulnerability blocking
|
||||
- GitHub release creation with artifacts
|
||||
- PyPI package publishing (stable releases only)
|
||||
- Production deployment
|
||||
|
||||
**Jobs:**
|
||||
- `validate-release` - Version format and metadata validation
|
||||
- `test-and-build` - Comprehensive testing and Python package build
|
||||
- `build-container` - Multi-arch container build with release tags
|
||||
- `security-scan` - Security scanning with critical vulnerability blocking
|
||||
- `create-release` - GitHub release with artifacts and changelog
|
||||
- `publish-package` - PyPI publishing (stable releases only)
|
||||
- `deploy-production` - Production deployment
|
||||
- `notify-release` - Release completion notification
|
||||
|
||||
### 4. `nightly.yml` - Nightly Builds
|
||||
**Triggers:** Daily at 2 AM UTC, manual dispatch
|
||||
|
||||
**Features:**
|
||||
- Change detection (skips if no commits in 24h)
|
||||
- Multi-Python version testing matrix
|
||||
- Performance testing
|
||||
- Comprehensive security scanning
|
||||
- Old image cleanup
|
||||
- Detailed reporting
|
||||
|
||||
**Jobs:**
|
||||
- `check-changes` - Detect if build is needed
|
||||
- `nightly-tests` - Test across Python versions (3.8-3.12)
|
||||
- `build-nightly` - Build nightly images with date/commit tags
|
||||
- `performance-test` - Basic performance validation
|
||||
- `security-scan-nightly` - Comprehensive security analysis
|
||||
- `cleanup-old-nightlies` - Remove old nightly images
|
||||
- `notify-results` - Build status notification
|
||||
|
||||
## Configuration
|
||||
|
||||
### Required Secrets
|
||||
|
||||
Set these secrets in your Gitea repository settings:
|
||||
|
||||
```bash
|
||||
# Container Registry
|
||||
CONTAINER_REGISTRY_USERNAME=your-registry-username
|
||||
CONTAINER_REGISTRY_PASSWORD=your-registry-password
|
||||
|
||||
# PyPI Publishing (for releases)
|
||||
PYPI_API_TOKEN=your-pypi-token
|
||||
|
||||
# GitHub (if using GitHub releases)
|
||||
GITHUB_TOKEN=your-github-token
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The workflows use these environment variables:
|
||||
|
||||
```yaml
|
||||
env:
|
||||
REGISTRY: gitea-http.taildb3494.ts.net
|
||||
IMAGE_NAME: will/unitforge
|
||||
```
|
||||
|
||||
Update these in each workflow file to match your registry and image name.
|
||||
|
||||
### Multi-Architecture Support
|
||||
|
||||
All workflows build for multiple architectures:
|
||||
- `linux/amd64` - Standard x86_64 architecture
|
||||
- `linux/arm64` - ARM64 architecture (Apple Silicon, ARM servers)
|
||||
|
||||
This is configured using Docker Buildx with the platform specification:
|
||||
```yaml
|
||||
platforms: linux/amd64,linux/arm64
|
||||
```
|
||||
|
||||
## Container Registry Integration
|
||||
|
||||
### Image Tags
|
||||
|
||||
Different workflows create different image tags:
|
||||
|
||||
**Main builds (build-container.yml):**
|
||||
- `main` - Latest from main branch
|
||||
- `develop` - Latest from develop branch
|
||||
- `latest` - Latest stable release
|
||||
|
||||
**Release builds (release.yml):**
|
||||
- `v1.2.3` - Specific version
|
||||
- `1.2` - Major.minor version
|
||||
- `1` - Major version (stable releases only)
|
||||
- `latest` - Latest stable release
|
||||
|
||||
**Nightly builds (nightly.yml):**
|
||||
- `nightly-20240101-abc1234` - Date and commit SHA
|
||||
- `nightly-latest` - Latest nightly build
|
||||
|
||||
### Registry Configuration
|
||||
|
||||
The workflows are configured for a self-hosted registry. To use a different registry:
|
||||
|
||||
1. Update the `REGISTRY` environment variable
|
||||
2. Ensure authentication secrets are set correctly
|
||||
3. Verify registry supports multi-arch manifests
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
|
||||
- `main` - Production-ready code
|
||||
- `develop` - Integration branch for features
|
||||
- `feature/*` - Feature branches (create PRs to develop)
|
||||
- `hotfix/*` - Critical fixes (create PRs to main)
|
||||
|
||||
### Release Process
|
||||
|
||||
1. **Prepare Release:**
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git tag v1.2.3
|
||||
git push origin v1.2.3
|
||||
```
|
||||
|
||||
2. **Automatic Process:**
|
||||
- Release workflow triggers
|
||||
- Tests run across all Python versions
|
||||
- Multi-arch container images built
|
||||
- Security scanning performed
|
||||
- GitHub release created
|
||||
- PyPI package published (if stable)
|
||||
- Production deployment triggered
|
||||
|
||||
3. **Manual Verification:**
|
||||
- Check workflow completion
|
||||
- Verify container images in registry
|
||||
- Test deployed application
|
||||
- Monitor for issues
|
||||
|
||||
### Local Development
|
||||
|
||||
Test builds locally using the Makefile:
|
||||
|
||||
```bash
|
||||
# Setup development environment
|
||||
make setup-dev
|
||||
|
||||
# Run tests and linting
|
||||
make dev
|
||||
|
||||
# Build container image locally
|
||||
make docker-buildx-local
|
||||
|
||||
# Test multi-arch build (requires buildx)
|
||||
make docker-buildx-setup
|
||||
docker buildx build --platform linux/amd64,linux/arm64 -t unitforge:test .
|
||||
```
|
||||
|
||||
## Debugging Workflows
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Missing Vendor Assets:**
|
||||
```
|
||||
Error: Missing bootstrap CSS file
|
||||
```
|
||||
Ensure all static assets are committed to the repository.
|
||||
|
||||
2. **Registry Authentication:**
|
||||
```
|
||||
Error: unauthorized
|
||||
```
|
||||
Verify `CONTAINER_REGISTRY_USERNAME` and `CONTAINER_REGISTRY_PASSWORD` secrets.
|
||||
|
||||
3. **Build Platform Issues:**
|
||||
```
|
||||
Error: multiple platforms feature is currently not supported
|
||||
```
|
||||
Ensure Docker Buildx is properly set up in the runner.
|
||||
|
||||
### Workflow Debugging
|
||||
|
||||
1. **Enable Debug Logging:**
|
||||
Add to workflow:
|
||||
```yaml
|
||||
env:
|
||||
ACTIONS_STEP_DEBUG: true
|
||||
ACTIONS_RUNNER_DEBUG: true
|
||||
```
|
||||
|
||||
2. **Test Locally:**
|
||||
Use `act` to test workflows locally:
|
||||
```bash
|
||||
act -j test -s CONTAINER_REGISTRY_USERNAME=test -s CONTAINER_REGISTRY_PASSWORD=test
|
||||
```
|
||||
|
||||
3. **Check Build Logs:**
|
||||
- View detailed logs in Gitea Actions UI
|
||||
- Check container registry for pushed images
|
||||
- Verify security scan results
|
||||
|
||||
## Security
|
||||
|
||||
### Image Scanning
|
||||
|
||||
All container images are scanned for vulnerabilities using Trivy:
|
||||
|
||||
- **PR builds:** Informational scanning
|
||||
- **Main builds:** Upload results to security dashboard
|
||||
- **Release builds:** Block on critical vulnerabilities
|
||||
- **Nightly builds:** Comprehensive analysis
|
||||
|
||||
### Secrets Management
|
||||
|
||||
- Use Gitea repository secrets for sensitive data
|
||||
- Never commit credentials to repository
|
||||
- Rotate secrets regularly
|
||||
- Use least-privilege access
|
||||
|
||||
### Build Security
|
||||
|
||||
- Multi-stage Dockerfile minimizes attack surface
|
||||
- Non-root user in containers
|
||||
- Dependency scanning included
|
||||
- Static analysis with security tools
|
||||
|
||||
## Monitoring and Notifications
|
||||
|
||||
### Build Status
|
||||
|
||||
Monitor workflow status:
|
||||
- Gitea Actions dashboard
|
||||
- Email notifications (configure in Gitea)
|
||||
- External monitoring (webhook integrations)
|
||||
|
||||
### Metrics
|
||||
|
||||
Track important metrics:
|
||||
- Build success rate
|
||||
- Build duration
|
||||
- Image size trends
|
||||
- Security vulnerability counts
|
||||
|
||||
### Alerts
|
||||
|
||||
Set up alerts for:
|
||||
- Failed builds on main/develop
|
||||
- Security vulnerabilities in releases
|
||||
- Performance regression in nightly builds
|
||||
- Registry storage usage
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding New Platforms
|
||||
|
||||
To support additional architectures:
|
||||
|
||||
1. Update platform list:
|
||||
```yaml
|
||||
platforms: linux/amd64,linux/arm64,linux/arm/v7
|
||||
```
|
||||
|
||||
2. Ensure base images support the platform
|
||||
3. Test builds on target architecture
|
||||
|
||||
### Custom Deployment
|
||||
|
||||
Modify deployment jobs for your infrastructure:
|
||||
|
||||
```yaml
|
||||
deploy-production:
|
||||
steps:
|
||||
- name: Deploy to Kubernetes
|
||||
run: |
|
||||
kubectl set image deployment/unitforge \
|
||||
unitforge=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}
|
||||
```
|
||||
|
||||
### Integration with External Tools
|
||||
|
||||
Add steps for external integrations:
|
||||
|
||||
```yaml
|
||||
- name: Update monitoring
|
||||
run: |
|
||||
curl -X POST "$MONITORING_WEBHOOK" \
|
||||
-d "version=${{ github.ref_name }}" \
|
||||
-d "image=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Performance Issues
|
||||
|
||||
If builds are slow:
|
||||
- Enable build caching (already configured)
|
||||
- Use faster runners if available
|
||||
- Parallelize independent jobs
|
||||
- Optimize Docker layer caching
|
||||
|
||||
### Storage Issues
|
||||
|
||||
Manage registry storage:
|
||||
- Implement cleanup policies
|
||||
- Use image compression
|
||||
- Remove unused layers
|
||||
- Monitor storage usage
|
||||
|
||||
### Network Issues
|
||||
|
||||
For registry connectivity problems:
|
||||
- Check network policies
|
||||
- Verify DNS resolution
|
||||
- Test registry endpoint manually
|
||||
- Review firewall rules
|
||||
|
||||
## Contributing
|
||||
|
||||
When modifying workflows:
|
||||
|
||||
1. Test changes in feature branch
|
||||
2. Document any new requirements
|
||||
3. Update this README if needed
|
||||
4. Ensure backward compatibility
|
||||
5. Test with actual builds before merging
|
||||
|
||||
For questions or issues with the CI/CD workflows, please create an issue in the repository.
|
||||
Reference in New Issue
Block a user