Resolving YAML Configuration File Conflicts

YAML Configuration Conflicts

YAML files present unique challenges during conflict resolution because indentation is syntactically meaningful. A single misplaced space can change the entire structure of the document. YAML conflicts commonly occur in CI/CD pipelines (GitHub Actions, GitLab CI), container orchestration (docker-compose.yml, Kubernetes manifests), and application configuration.

Common YAML Conflict Example

services:
  api:
<<<<<<< HEAD
    image: node:18-alpine
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://db:5432/app
=======
    image: node:20-alpine
    ports:
      - "3000:3000"
      - "9229:9229"
    environment:
      NODE_ENV: development
      DEBUG: "true"
>>>>>>> feature/debug-mode

Why YAML Conflicts Are Dangerous

1. Invisible errors: A tab character or wrong indentation level produces valid YAML that means something completely different from what you intended.
2. Block scalars: Multi-line strings using | or > syntax can be misaligned during conflict resolution.
3. Anchors and aliases: YAML features like &anchor and *alias can break if the referenced block is modified in one version.

Resolution Strategy

• Always use Manual Edit for YAML conflicts to precisely control indentation.
• After resolving, validate the YAML using a linter or a YAML formatter tool.
• For docker-compose files, run docker-compose config to verify the resolved file parses correctly.
• For GitHub Actions, use the workflow syntax checker before committing.

Preserving Indentation

When using the Manual Edit option in the Git Conflict Resolver, be careful to maintain consistent indentation (typically 2 spaces for YAML). Copy from one side as a starting point, then add the missing elements from the other side.