new: pkg: add CI/CD improvements - add new CI workflow - & improve the deployment w/ tests #10
This commit is contained in:
443
docs/CI_CD.md
Normal file
443
docs/CI_CD.md
Normal file
@@ -0,0 +1,443 @@
|
||||
# CI/CD Integration Guide
|
||||
|
||||
This document explains how automated tests are integrated into the MineSeeker deployment pipeline using Gitea Actions.
|
||||
|
||||
## Overview
|
||||
|
||||
MineSeeker uses **Gitea Actions** (GitHub Actions compatible) for continuous integration and deployment:
|
||||
|
||||
- **CI Pipeline** (`.gitea/workflows/ci.yml`) - Runs on every push/PR to main/develop
|
||||
- **CD Pipeline** (`.gitea/workflows/deploy.yml`) - Runs on version tags, includes tests before deployment
|
||||
|
||||
---
|
||||
|
||||
## CI Workflow (Continuous Integration)
|
||||
|
||||
**Trigger:** Push or Pull Request to `main` or `develop` branches
|
||||
|
||||
**File:** `.gitea/workflows/ci.yml`
|
||||
|
||||
### Jobs
|
||||
|
||||
#### 1. **Tests Job**
|
||||
|
||||
Runs the full PHPUnit test suite with:
|
||||
|
||||
- PostgreSQL 18 service container
|
||||
- PHP 8.3 with required extensions
|
||||
- Composer dependency installation
|
||||
- Node.js for asset building
|
||||
- Database setup and migrations
|
||||
- 71 PHPUnit tests with testdox output
|
||||
|
||||
**Steps:**
|
||||
1. Checkout code
|
||||
2. Setup PHP 8.3 with extensions (pdo_pgsql, gd, intl, zip, sodium)
|
||||
3. Validate `composer.json`
|
||||
4. Cache and install Composer dependencies
|
||||
5. Setup Node.js 20 and install dependencies
|
||||
6. Build frontend assets with Vite
|
||||
7. Create `.env.test` configuration
|
||||
8. Setup test database with migrations
|
||||
9. Run PHPUnit tests with `--testdox` output
|
||||
10. (Optional) Generate coverage report on PRs
|
||||
|
||||
#### 2. **Lint Job**
|
||||
|
||||
Code quality checks:
|
||||
|
||||
- ESLint for JavaScript/JSX
|
||||
- PHP-CS-Fixer (if installed)
|
||||
|
||||
---
|
||||
|
||||
## CD Workflow (Continuous Deployment)
|
||||
|
||||
**Trigger:** Push of version tags (e.g., `v1.0.0`, `v1.2.3`)
|
||||
|
||||
**File:** `.gitea/workflows/deploy.yml`
|
||||
|
||||
### Jobs
|
||||
|
||||
#### 1. **Test Job** (Pre-deployment)
|
||||
|
||||
**Critical:** Deployment only proceeds if tests pass.
|
||||
|
||||
- Runs same test suite as CI workflow
|
||||
- Uses `--stop-on-failure` flag for fast feedback
|
||||
- Blocks deployment on any test failure
|
||||
|
||||
#### 2. **Deploy Job** (Production Deployment)
|
||||
|
||||
**Depends on:** `test` job must complete successfully
|
||||
|
||||
**Steps:**
|
||||
1. Checkout tagged version
|
||||
2. Write production `.env` from secrets
|
||||
3. Build Docker image
|
||||
4. Run database migrations
|
||||
5. Clear production cache
|
||||
6. Start/restart services with `docker compose up -d`
|
||||
7. Health check (curl to verify app is running)
|
||||
8. Notify success/failure
|
||||
|
||||
---
|
||||
|
||||
## Configuration Requirements
|
||||
|
||||
### Gitea Repository Variables
|
||||
|
||||
Set these in Gitea repository settings:
|
||||
|
||||
```
|
||||
PROD_APP_DIR=/path/to/production/app
|
||||
```
|
||||
|
||||
### Gitea Repository Secrets
|
||||
|
||||
```
|
||||
PROD_ENV_FILE=<contents of production .env file>
|
||||
```
|
||||
|
||||
### Test Database Configuration
|
||||
|
||||
The CI/CD pipeline uses a PostgreSQL service container with these credentials:
|
||||
|
||||
```env
|
||||
POSTGRES_USER=mineseeker_test
|
||||
POSTGRES_PASSWORD=test_password
|
||||
POSTGRES_DB=mineseeker_test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running Tests Locally
|
||||
|
||||
Before pushing, run tests locally to catch issues early:
|
||||
|
||||
```bash
|
||||
# Setup test database (first time only)
|
||||
make test-db-setup
|
||||
|
||||
# Run tests
|
||||
make test
|
||||
|
||||
# Run with testdox output
|
||||
vendor/bin/phpunit --testdox
|
||||
|
||||
# Run with coverage
|
||||
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html=var/coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Workflow
|
||||
|
||||
### Standard Deployment Process
|
||||
|
||||
1. **Develop features** on feature branches
|
||||
2. **Open Pull Request** to `develop` or `main`
|
||||
- CI workflow runs automatically
|
||||
- Tests must pass before merge
|
||||
3. **Merge PR** after review and passing tests
|
||||
4. **Create version tag** when ready to deploy:
|
||||
```bash
|
||||
git tag -a v1.2.3 -m "Release version 1.2.3"
|
||||
git push origin v1.2.3
|
||||
```
|
||||
5. **Deployment runs automatically:**
|
||||
- Tests run first
|
||||
- If tests pass, Docker image builds
|
||||
- Migrations run
|
||||
- Services restart
|
||||
- Health check verifies deployment
|
||||
|
||||
### Rollback Process
|
||||
|
||||
If deployment fails or issues are discovered:
|
||||
|
||||
```bash
|
||||
# Tag and deploy previous stable version
|
||||
git push origin v1.2.2
|
||||
|
||||
# Or SSH to production and manually rollback
|
||||
cd /path/to/production/app
|
||||
git checkout v1.2.2
|
||||
docker compose build
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Suite Details
|
||||
|
||||
### Test Coverage
|
||||
|
||||
The CI/CD pipeline runs **71 tests** across:
|
||||
|
||||
- **Controller Tests** (29 tests)
|
||||
- GameController, ProfileController, SecurityController
|
||||
- HTTP status codes, authentication, routing
|
||||
|
||||
- **DTO Tests** (9 tests)
|
||||
- ProfileGameDto, ProfileStatsDto, ProfileChartDataDto
|
||||
- Serialization, null handling, calculations
|
||||
|
||||
- **Entity Tests** (8 tests)
|
||||
- UserStats calculations and defaults
|
||||
|
||||
- **Service Tests** (13 tests)
|
||||
- MercureJwtService, RecaptchaService
|
||||
- Token generation, API verification
|
||||
|
||||
- **Integration Tests** (12 tests)
|
||||
- Factory usage examples
|
||||
- Database isolation
|
||||
|
||||
### Test Execution Time
|
||||
|
||||
Typical test suite runtime: **6-8 seconds**
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Committing
|
||||
|
||||
✅ **Always run tests locally:**
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
✅ **Check code style:**
|
||||
```bash
|
||||
vendor/bin/php-cs-fixer fix --dry-run
|
||||
npm run lint
|
||||
```
|
||||
|
||||
✅ **Verify assets build:**
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
### When Creating PRs
|
||||
|
||||
✅ **Wait for CI checks** to pass before requesting review
|
||||
|
||||
✅ **Fix failing tests** immediately - don't merge broken code
|
||||
|
||||
✅ **Review test output** in Gitea Actions logs
|
||||
|
||||
### When Deploying
|
||||
|
||||
✅ **Tag semantic versions:** `v1.2.3` (major.minor.patch)
|
||||
|
||||
✅ **Write meaningful tag messages:**
|
||||
```bash
|
||||
git tag -a v1.2.3 -m "Add bonus points to battle cards, fix avatar upload bug"
|
||||
```
|
||||
|
||||
✅ **Monitor deployment logs** in Gitea Actions
|
||||
|
||||
✅ **Verify health check** passes after deployment
|
||||
|
||||
✅ **Test critical features** in production after deployment
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tests Pass Locally but Fail in CI
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. **Database state:** CI uses fresh database, local may have leftover data
|
||||
```bash
|
||||
make test-db-reset # Reset local test database
|
||||
```
|
||||
|
||||
2. **Environment differences:** Check `.env.test` matches CI configuration
|
||||
|
||||
3. **Cached dependencies:** CI caches may be stale
|
||||
- Clear cache in Gitea Actions settings
|
||||
- Or add `--no-cache` to composer install
|
||||
|
||||
### Deployment Fails After Tests Pass
|
||||
|
||||
**Common issues:**
|
||||
|
||||
1. **Migration conflicts:** Manually run migrations on production
|
||||
```bash
|
||||
docker compose run --rm app php bin/console doctrine:migrations:migrate
|
||||
```
|
||||
|
||||
2. **Missing environment variables:** Check `PROD_ENV_FILE` secret is up-to-date
|
||||
|
||||
3. **Docker build errors:** Check Dockerfile and build context
|
||||
|
||||
4. **Health check timeout:** Increase sleep time or check application startup
|
||||
|
||||
### Database Migration Issues
|
||||
|
||||
If migrations fail during deployment:
|
||||
|
||||
```bash
|
||||
# SSH to production server
|
||||
cd /path/to/production/app
|
||||
|
||||
# Check migration status
|
||||
docker compose run --rm app php bin/console doctrine:migrations:status
|
||||
|
||||
# Manually run migrations
|
||||
docker compose run --rm app php bin/console doctrine:migrations:migrate --no-interaction
|
||||
|
||||
# If migration is stuck, mark as executed
|
||||
docker compose run --rm app php bin/console doctrine:migrations:version YYYYMMDDHHMMSS --add
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring and Notifications
|
||||
|
||||
### Viewing CI/CD Logs
|
||||
|
||||
1. Go to Gitea repository
|
||||
2. Click **Actions** tab
|
||||
3. Select workflow run
|
||||
4. View detailed logs for each step
|
||||
|
||||
### Setting Up Notifications
|
||||
|
||||
**Gitea webhook notifications:**
|
||||
|
||||
Configure webhooks in repository settings to notify:
|
||||
- Slack/Discord when builds fail
|
||||
- Email on deployment success/failure
|
||||
- Custom endpoints for monitoring systems
|
||||
|
||||
**Example webhook payload:**
|
||||
```json
|
||||
{
|
||||
"event": "workflow_run",
|
||||
"repository": "Mine",
|
||||
"workflow": "deploy.yml",
|
||||
"status": "success",
|
||||
"tag": "v1.2.3"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Running Tests with Coverage
|
||||
|
||||
Enable coverage in CI (requires Xdebug):
|
||||
|
||||
```yaml
|
||||
- name: Run tests with coverage
|
||||
run: |
|
||||
XDEBUG_MODE=coverage vendor/bin/phpunit \
|
||||
--coverage-clover=coverage.xml \
|
||||
--coverage-html=var/coverage
|
||||
```
|
||||
|
||||
### Parallel Test Execution
|
||||
|
||||
For larger test suites, use ParaTest:
|
||||
|
||||
```bash
|
||||
composer require --dev brianium/paratest
|
||||
```
|
||||
|
||||
```yaml
|
||||
- name: Run tests in parallel
|
||||
run: vendor/bin/paratest --processes=4
|
||||
```
|
||||
|
||||
### Database Seeding for E2E Tests
|
||||
|
||||
Add step before tests:
|
||||
|
||||
```yaml
|
||||
- name: Seed test data
|
||||
run: |
|
||||
php bin/console doctrine:fixtures:load --no-interaction --env=test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Secrets Management
|
||||
|
||||
❗ **Never commit secrets to repository**
|
||||
|
||||
✅ **Use Gitea secrets** for sensitive data:
|
||||
- `PROD_ENV_FILE` - Production environment variables
|
||||
- Database credentials
|
||||
- API keys
|
||||
|
||||
✅ **Rotate secrets regularly**
|
||||
|
||||
✅ **Use environment-specific secrets** (staging, production)
|
||||
|
||||
### Database Security
|
||||
|
||||
✅ **Test database is isolated** - No production data access
|
||||
|
||||
✅ **Credentials are ephemeral** - Service containers use temporary passwords
|
||||
|
||||
✅ **No data persistence** - Test database recreated on each run
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Caching Strategies
|
||||
|
||||
CI/CD workflows cache:
|
||||
|
||||
1. **Composer dependencies** - `vendor/` directory
|
||||
2. **Node modules** - `node_modules/` directory
|
||||
3. **Docker layers** - Image build cache
|
||||
|
||||
### Reducing Build Time
|
||||
|
||||
✅ **Use `composer install --no-dev`** in production builds
|
||||
|
||||
✅ **Multi-stage Docker builds** - Separate assets from PHP
|
||||
|
||||
✅ **Parallel jobs** - Tests and linting run concurrently
|
||||
|
||||
✅ **Skip unnecessary steps** - Use conditionals (`if:` statements)
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
|
||||
- [ ] Automated browser tests with Symfony Panther
|
||||
- [ ] Visual regression testing for UI changes
|
||||
- [ ] Performance benchmarking in CI
|
||||
- [ ] Automated security scanning (Symfony Security Checker)
|
||||
- [ ] Staging environment deployments before production
|
||||
- [ ] Blue-green deployment strategy
|
||||
- [ ] Automated rollback on health check failure
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Gitea Actions Documentation:** https://docs.gitea.com/usage/actions/overview
|
||||
- **GitHub Actions Reference:** https://docs.github.com/en/actions (compatible syntax)
|
||||
- **PHPUnit Documentation:** https://phpunit.de/documentation.html
|
||||
- **Symfony Testing:** https://symfony.com/doc/current/testing.html
|
||||
- **Docker Compose:** https://docs.docker.com/compose/
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-04-21
|
||||
**MineSeeker Version:** 1.0.0
|
||||
**CI/CD Platform:** Gitea Actions
|
||||
Reference in New Issue
Block a user