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

Select array, object, or document separation based on your needs.

3

Merge Configs

Combine files into an array, object wrapper, or multi-document YAML output.

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 browser tool does not perform a semantic deep merge; use a YAML-aware tool such as yq when you need recursive key merging.

Use a YAML-aware deep merge for Kubernetes and Docker Compose files that share keys like services, volumes, or env. Use this browser tool when you want to combine files into an array, object wrapper, or multi-document YAML for review.

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}.

Most YAML merge tools default to shallow merge because it is simpler and more predictable. If you need deep merge behavior, look for tools that explicitly support recursive merging or use a library like yq with the merge operator.

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), but the tool works for pre-merge preview or creating a single file for deployment.

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. Use shallow merge when environment-specific values should override base values. Use deep merge when combining role defaults with environment-specific overrides.

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.

Special characters in values need quoting. Colons, brackets, braces, and leading/trailing spaces require quotes. Example: url: http://example.com needs to be url: "http://example.com" because the colon after http confuses the parser. Use quotes for any value containing special characters.

Validate YAML before merging: paste into yamllint.com or use the VS Code YAML extension (Red Hat's YAML extension). Both catch syntax errors, indentation problems, and duplicate keys. Fix all validation errors before attempting to merge files.

Related Articles