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:

POSTGRES_USER=mineseeker_test
POSTGRES_PASSWORD=test_password
POSTGRES_DB=mineseeker_test

---

Running Tests Locally

Before pushing, run tests locally to catch issues early:

# 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:

   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:

# 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:

make test

✅ Check code style:

vendor/bin/php-cs-fixer fix --dry-run
npm run lint

✅ Verify assets build:

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:

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

   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

   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:

# 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:

{
  "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):

- 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:

composer require --dev brianium/paratest

- name: Run tests in parallel
  run: vendor/bin/paratest --processes=4

Database Seeding for E2E Tests

Add step before tests:

- 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