MineSeeker/docs/CI_CD.md

# 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