Version Control

Overview

The SGIVU Config Repository is the source of truth for all microservice configurations. Proper version control practices ensure configuration changes are tracked, reviewed, and can be rolled back if needed.

Configuration changes can have significant impact on running services. Treat configuration with the same care as application code.

Git Workflow

The repository follows a standard Git workflow with environment-specific considerations:

Create a Feature Branch

Always create a branch for configuration changes

git checkout -b config/update-auth-database-settings

Use descriptive branch names:

config/ prefix for configuration changes
Service or area being modified
Brief description of change

Make Your Changes

Edit the appropriate YAML files:

# Edit configuration files
vim sgivu-auth-dev.yml
vim sgivu-auth-prod.yml

# Validate with yamllint
yamllint *.yml

Commit with Descriptive Messages

Write clear commit messages that explain the change

git add sgivu-auth-dev.yml sgivu-auth-prod.yml
git commit -m "Update auth service database connection pool settings

- Increase max pool size from 10 to 20 for better throughput
- Add connection timeout of 30s to prevent hanging connections
- Applied to both dev and prod environments"

Push and Create Pull Request

Push your branch and open a PR for review

git push origin config/update-auth-database-settings

Create a PR with:

Clear title describing the change
Detailed description of what changed and why
Which services and environments are affected
Testing performed

Review and Merge

After approval, merge to main branch

git checkout main
git pull origin main
git merge --no-ff config/update-auth-database-settings
git push origin main

Commit Message Best Practices

Structure

Follow this commit message format:

<summary line: what changed>

<detailed description: why it changed>
- Impact on services
- Environments affected
- Any related changes

Good Examples

# ✅ Good - clear and descriptive
git commit -m "Enable SQL logging in dev environment for auth service

Added show-sql and format_sql properties to aid in debugging
login issues reported by QA team. Only affects dev environment.

- sgivu-auth-dev.yml: spring.jpa.show-sql = true
- sgivu-auth-dev.yml: spring.jpa.properties.hibernate.format_sql = true"

# ✅ Good - explains security change
git commit -m "Restrict actuator endpoints in production

Limited exposed actuator endpoints to health, info, and prometheus
for security hardening. Development remains fully open for debugging.

- sgivu-gateway-prod.yml: management.endpoints.web.exposure.include
- Affects production only
- Aligns with security audit recommendations"

# ✅ Good - documents synchronization
git commit -m "Synchronize Redis configuration across all environments

Standardized Redis connection settings for gateway session storage:
- Consistent timeout: 1h
- Namespace: spring:session:sgivu-gateway
- Connection pooling parameters aligned

Affects: sgivu-gateway.yml, sgivu-gateway-dev.yml, sgivu-gateway-prod.yml"

Poor Examples

# ❌ Bad - too vague
git commit -m "Update config"

# ❌ Bad - no context
git commit -m "Change database URL"

# ❌ Bad - missing why
git commit -m "Modified sgivu-auth-dev.yml"

A good commit message answers: What changed, Why it changed, and Where (which services/environments) it applies.

Documenting Critical Changes

From the repository conventions:

Documenta en PRs cambios que afecten comportamiento crítico.

Certain configuration changes require extra documentation in pull requests:

Critical Changes That Need Documentation

Security Settings

OAuth2 configuration, authentication, authorization, CORS, CSP

Database Changes

Connection strings, credentials, pool sizes, schema migrations

Service Dependencies

Eureka settings, service URLs, load balancing, circuit breakers

Performance Tuning

Timeouts, thread pools, cache sizes, rate limits

Pull Request Template Example

## Summary
Update database connection pool settings for auth service to handle increased load

## Changes
- **sgivu-auth-dev.yml**: Increased max pool size from 10 to 20
- **sgivu-auth-prod.yml**: Increased max pool size from 10 to 30
- Added connection timeout of 30 seconds to both environments

## Motivation
QA reported slow login times during load testing. Database connection
pool was saturated under 100 concurrent users. These changes allow the
auth service to handle up to 200 concurrent connections.

## Impact
- **Services Affected**: sgivu-auth
- **Environments**: dev, prod
- **Breaking Changes**: None
- **Requires Restart**: Yes, sgivu-auth service must be restarted

## Testing
- [x] Validated YAML syntax with yamllint
- [x] Tested in local Docker environment
- [x] Load tested with 150 concurrent users in dev
- [x] Verified no connection timeout errors

## Rollback Plan
If issues occur, revert to previous commit:
```bash
git revert <this-commit-hash>

Or manually reduce pool size back to original values. Closes #42 - Auth service connection pool saturation

## Synchronizing Values Across Environments

From the repository conventions:

> **Sincroniza puertos, URLs y credenciales entre entornos.**

Certain configuration values should remain consistent across environments:

### Values to Synchronize

**Service Ports**: Keep base service ports consistent (use environment variables for overrides if needed)

```yaml
# sgivu-auth.yml (base)
server:
  port: ${PORT:9000}

Service Discovery URLs: Eureka URLs should follow the same pattern

# All services
eureka:
  client:
    service-url:
      defaultZone: ${EUREKA_URL:http://sgivu-discovery:8761/eureka}

Structural Settings: Common Spring Boot properties should match

# All service base files
spring:
  jpa:
    open-in-view: false

Security Baselines: Core security settings should be synchronized (with environment-specific adjustments)

# Base: restrict by default
management:
  endpoints:
    web:
      exposure:
        include: health, info

# Dev: can be more permissive
management:
  endpoints:
    web:
      exposure:
        include: "*"

Detecting Drift

Periodically compare environment configurations to detect drift:

# Compare dev and prod configurations
diff -u sgivu-auth-dev.yml sgivu-auth-prod.yml

# Or use a visual diff tool
git diff --no-index sgivu-auth-dev.yml sgivu-auth-prod.yml

Testing Before Merging

Always validate configuration changes before merging:

Local Testing with Docker Compose

Start Config Server

Launch the Config Server with your changes

cd ../sgivu-docker-compose
docker compose up -d sgivu-config

Verify Configuration Endpoint

Test that the Config Server can read your changes

# Test dev profile
curl http://localhost:8888/sgivu-auth/dev | jq .

# Test prod profile
curl http://localhost:8888/sgivu-auth/prod | jq .

Start Affected Services

Launch the services that use the modified configuration

docker compose up -d sgivu-auth

# Check service logs for configuration errors
docker compose logs -f sgivu-auth

Functional Testing

Test that the services work as expected with new configuration

# Health check
curl http://localhost:9000/actuator/health

# Test actual functionality
# (login, API calls, etc.)

Validation Checklist

YAML syntax validated with yamllint
Config Server can parse all files
Services start successfully with new configuration
No error logs related to missing or invalid properties
Functional testing passes
Performance meets expectations (if tuning changes)
Security settings verified (if security changes)

How Configuration Changes Propagate

Understanding the propagation flow helps with testing and troubleshooting:

Propagation Methods

Config Server Restart

When: Immediately applies changes by restarting the Config Server

docker compose restart sgivu-config

Impact: All services will get new configuration on their next restart or refreshUse case: Any configuration change

Service Restart

When: Service restarts and fetches fresh configuration from Config Server

docker compose restart sgivu-auth

Impact: Only the restarted service gets new configurationUse case: Applying changes to specific services

Actuator Refresh Endpoint

When: Dynamic refresh without restart (if service supports it)

curl -X POST http://localhost:9000/actuator/refresh

Impact: Service reloads configuration without downtimeUse case: Non-structural changes (e.g., feature flags, logging levels)Limitation: Not all properties support dynamic refresh

Full Restart

When: Restart both Config Server and all services

docker compose restart sgivu-config
docker compose restart  # All services

Impact: Complete system refresh with all new configurationUse case: Major configuration overhauls, troubleshooting

Rollback Strategies

When configuration changes cause issues, roll back quickly:

Git Revert (Recommended)

Create a revert commit to undo changes:

# Find the problematic commit
git log --oneline

# Revert the commit
git revert <commit-hash>

# Push the revert
git push origin main

# Restart Config Server to apply
docker compose restart sgivu-config

Using git revert maintains history and makes it clear when and why a rollback occurred.

Emergency Manual Edit

For critical production issues, edit directly and commit:

# Edit the problematic file
vim sgivu-auth-prod.yml

# Commit the fix
git add sgivu-auth-prod.yml
git commit -m "HOTFIX: Rollback database connection pool to stable values

Reverted max pool size from 30 to 10 due to database CPU saturation.
Production auth service experiencing 500 errors.

Reverting to last known stable configuration."

git push origin main

# Restart services immediately
docker compose restart sgivu-config sgivu-auth

Reset to Specific Commit

For severe issues, reset to a known-good state:

# Find the last good commit
git log --oneline

# Reset to that commit
git reset --hard <good-commit-hash>

# Force push (use with caution!)
git push --force origin main

# Restart all services
docker compose restart

Only use git reset --hard and force push in emergencies. It rewrites history and can cause issues for other team members.

Rollback Testing

After rollback:

# Verify configuration is loaded
curl http://localhost:8888/sgivu-auth/prod | jq .

# Check service health
curl http://localhost:9000/actuator/health

# Monitor logs
docker compose logs -f sgivu-auth

# Verify functionality
# (test login, API calls, etc.)

Configuration Change Workflow Summary

Plan

Identify what needs to change and why
Determine which environments are affected
Consider rollback approach

Implement

Create feature branch
Edit YAML files
Validate with yamllint
Write descriptive commit messages

Test

Test locally with Docker Compose
Verify Config Server can parse changes
Ensure services start and function correctly

Review

Create detailed pull request
Document critical changes
Get team approval

Deploy

Merge to main branch
Restart Config Server
Restart affected services
Monitor for issues

Verify

Check service health
Test functionality
Monitor logs and metrics
Roll back if needed

Best Practices Summary

Use feature branches - Never commit directly to main
Write descriptive commits - Explain what, why, and where
Document critical changes - Security, performance, and dependencies need extra detail
Synchronize across environments - Keep ports, URLs, and structures consistent
Test before merging - Validate locally with Docker Compose
Understand propagation - Know how changes reach running services
Have a rollback plan - Be ready to revert quickly if issues arise
Monitor after changes - Watch logs and metrics after deploying configuration changes
Review as a team - Configuration changes should be peer-reviewed like code
Keep history clean - Use meaningful commits and avoid force pushes unless necessary

Common Patterns

Best Practices

Overview

Git Workflow

Commit Message Best Practices

Structure

Good Examples

Poor Examples

Documenting Critical Changes

Critical Changes That Need Documentation

Security Settings

Database Changes

Service Dependencies

Performance Tuning

Pull Request Template Example

Detecting Drift

Testing Before Merging

Local Testing with Docker Compose

Validation Checklist

How Configuration Changes Propagate

Propagation Methods

Rollback Strategies

Git Revert (Recommended)

Emergency Manual Edit

Reset to Specific Commit

Rollback Testing

Configuration Change Workflow Summary

Best Practices Summary

Build docs developers (and LLMs) love

Common Patterns

Best Practices

​Overview

​Git Workflow

​Commit Message Best Practices

​Structure

​Good Examples

​Poor Examples

​Documenting Critical Changes

​Critical Changes That Need Documentation

Security Settings

Database Changes

Service Dependencies

Performance Tuning

​Pull Request Template Example

​Related Issues

​Detecting Drift

​Testing Before Merging

​Local Testing with Docker Compose

​Validation Checklist

​How Configuration Changes Propagate

​Propagation Methods

​Rollback Strategies

​Git Revert (Recommended)

​Emergency Manual Edit

​Reset to Specific Commit

​Rollback Testing

​Configuration Change Workflow Summary

​Best Practices Summary

Build docs developers (and LLMs) love

Overview

Git Workflow

Commit Message Best Practices

Structure

Good Examples

Poor Examples

Documenting Critical Changes

Critical Changes That Need Documentation

Pull Request Template Example

Related Issues

Detecting Drift

Testing Before Merging

Local Testing with Docker Compose

Validation Checklist

How Configuration Changes Propagate

Propagation Methods

Rollback Strategies

Git Revert (Recommended)

Emergency Manual Edit

Reset to Specific Commit

Rollback Testing

Configuration Change Workflow Summary

Best Practices Summary