merge-json-files.com

Merge YAML Files Online - Free YAML Merger Tool

This tool combines multiple YAML files into one. Used by DevOps engineers and developers working with Kubernetes configs, Docker Compose files, GitHub Actions workflows, and Ansible playbooks. Runs entirely in your browser, free.

Before & After

YAML merge in action

Input: Separate YAML Files
yaml
# config-dev.yaml
environment: development
database:
  host: localhost
  port: 5432

# config-prod.yaml
environment: production
database:
  host: prod-db.example.com
  port: 5432
Output: Array of Documents (default)
yaml
merged:
  # From config-dev.yaml
  - environment: development
    database:
      host: localhost
      port: 5432
  # From config-prod.yaml
  - environment: production
    database:
      host: prod-db.example.com
      port: 5432

How It Works

Four simple steps

1

Upload YAML Files

Drop multiple .yaml or .yml files directly into the merger interface.

2

Choose Strategy

Pick Array, Deep Merge, Object with Keys, or Separate Documents.

3

Merge Configs

Valid files are parsed and combined; files with syntax errors are flagged and skipped.

4

Download Result

Get merged YAML file ready for deployment or configuration.

Use Cases

Real-world scenarios

Environment Configs

Combine base configuration with environment-specific overrides for dev, staging, and production deployments.

Kubernetes Manifests

Consolidate multiple resource definitions into single files for easier kubectl apply and atomic deployments.

CI/CD Pipelines

Merge pipeline configuration fragments for different stages, environments, or teams into complete workflows.

Docker Compose

Combine service definitions from multiple compose files into comprehensive stack configurations.

FAQ

Common questions

Programmatic Merge

Python & Bash

Pythonmerge_yaml.py
import yaml

def merge_yaml_files(files, strategy="array", root_key="merged"):
    merged_data = []
    
    for filepath in files:
        with open(filepath, 'r') as f:
            data = yaml.safe_load(f)
            merged_data.append(data)
    
    if strategy == "array":
        output = {root_key: merged_data}
    elif strategy == "object":
        output = {root_key: {}}
        for i, filepath in enumerate(files):
            key = filepath.replace('.yaml', '').replace('.yml', '')
            output[root_key][key] = merged_data[i]
    else:  # document
        output = merged_data
    
    with open("merged.yaml", 'w') as f:
        if strategy == "document":
            yaml.dump_all(output, f, default_flow_style=False)
        else:
            yaml.dump(output, f, default_flow_style=False)
    
    print(f"Merged {len(files)} YAML files")

files = ["config-dev.yaml", "config-prod.yaml"]
merge_yaml_files(files, strategy="object", root_key="environments")
Bashmerge_yaml.sh
#!/bin/bash
# Merge YAML files with document separators

OUTPUT="merged.yaml"

# Clear output file
> "$OUTPUT"

# Merge all YAML files
for file in configs/*.yaml; do
  if [ -f "$file" ]; then
    echo "# From $file" >> "$OUTPUT"
    cat "$file" >> "$OUTPUT"
    echo "---" >> "$OUTPUT"
  fi
done

# Remove trailing separator
sed -i '$ d' "$OUTPUT"

echo "Merged YAML files into $OUTPUT"

Complete Guide

In-depth walkthrough

Deep merge vs shallow merge for YAML - which you need

Shallow merge: top-level keys from all files are combined. If two files have the same top-level key, the last file's value wins and overwrites the first. Example: file1 has database: postgres and file2 has database: mysql. Shallow merge gives you database: mysql.

Deep merge: nested keys are merged recursively. If both files have a services key with different sub-keys, deep merge combines them instead of overwriting. This tool's Deep Merge strategy does exactly that: mappings are merged recursively, the later file wins for the same scalar key, and lists are replaced by default (you can switch to concatenating them).

Use Deep Merge for config files that share keys like services, volumes, or env. Use Array of Documents, Object with Keys, or Separate Documents when every file should stay intact as its own item, section, or document.

Before shallow merge: file1 port: 3000, file2 port: 8080. After: port: 8080. Before deep merge: file1 config: {timeout: 30}, file2 config: {retries: 3}. After: config: {timeout: 30, retries: 3}.

Order matters for deep merge: upload (or reorder) files so the base comes first and overrides come last. Deep Merge works on parsed data, so comments from the source files are not carried over and anchors are expanded into plain values.

Merging Kubernetes, Docker Compose, and GitHub Actions files

Kubernetes: merging base config with environment-specific overlays is common for multi-environment deployments. For deployable overlays, use Kubernetes-native tools such as Kustomize or a YAML-aware merge tool. Use this browser merger for combining manifests into one multi-document file for review, then validate with kubectl apply --dry-run.

Docker Compose: merging a base docker-compose.yml with a docker-compose.override.yml is standard practice. Docker does this natively with the -f flag (docker-compose -f base.yml -f override.yml up), and Deep Merge in this tool gives a similar single-file preview. Compose has a few special rules (for example, some lists such as ports are combined rather than replaced), so confirm the result with docker compose config.

GitHub Actions: combining reusable workflow fragments lets you build complex workflows from smaller pieces. YAML anchors and aliases may need manual cleanup after merging because they do not work across separate files. Convert anchors to explicit values or use GitHub's reusable workflows feature instead.

Ansible: merging variable files from different environments (dev, staging, prod) creates a single vars file for playbook execution. Deep Merge with the base file first lets environment-specific values override base values while keeping keys the override file does not mention.

For all these workflows, test the merged output with the target tool before deploying. Run kubectl apply --dry-run, docker-compose config, or ansible-playbook --syntax-check to catch merge errors early.

YAML syntax issues that cause merge failures

Indentation errors are the most common problem. YAML uses spaces, not tabs. Tabs will break the parser with cryptic errors like "mapping values are not allowed here". Set your editor to convert tabs to spaces and use consistent indentation (2 or 4 spaces, not mixed).

Duplicate keys in the same file are not allowed in strict YAML. If you have two name: keys at the same level, the parser will reject it or silently use the last value. Check for duplicates before merging. Some parsers allow duplicates but this is non-standard behavior.

Some special characters in values need quoting. A colon followed by a space, a value starting with [, {, *, & or #, and leading/trailing spaces all require quotes. A colon without a following space is fine: url: http://example.com parses as a plain string, but title: Note: read me must be written title: "Note: read me".

This tool parses every file you add and flags syntax errors, tab indentation, and duplicate keys with the line number; flagged files are skipped when merging. For style rules (line length, key ordering) use yamllint or Red Hat's YAML extension for VS Code.

Related Articles