chore(deps): update dependency pygments to v2.20.0

Ref: https://github.com/devture/com.devture.ansible.role.playbook_help/pull/4

.github/workflows/matrix.yml

@@ -9,34 +9,37 @@ name: Matrix CI
 
 on: [push, pull_request]  # yamllint disable-line rule:truthy
 
+permissions:
+  contents: read
+
 jobs:
-  yamllint:
-    name: yamllint
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out
-        uses: actions/checkout@v6
-      - name: Run yamllint
-        uses: frenck/action-yamllint@v1.5.0
-  ansible-lint:
-    name: ansible-lint
+  prek:
+    name: Run prek hooks
     runs-on: ubuntu-latest
+    container:
+      image: docker.io/archlinux:base-devel
+
     steps:
+      # git must be installed before checkout so it does a proper clone
+      # (with .git directory) instead of a tarball download.
+      - name: Install git
+        run: pacman -Sy --noconfirm git
+
       - name: Check out
         uses: actions/checkout@v6
 
-      - name: Run ansible-lint
-        uses: ansible/ansible-lint@v26.3.0
+      - name: Restore prek cache
+        uses: actions/cache@v5
         with:
-          args: "roles/custom"
-          setup_python: "true"
-          working_directory: ""
-          requirements_file: requirements.yml
-  precommit:
-    name: Run pre-commit
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-      - name: Run pre-commit
-        uses: pre-commit/action@v3.0.1
+          path: var/prek
+          key: arch-prek-v1-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Install dependencies
+        run: pacman -S --noconfirm --needed just mise python
+
+      - name: Run prek hooks
+        run: |
+          # The checkout action sets safe.directory using its own bundled
+          # git, which is separate from the pacman-installed git that prek uses.
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          just prek-run-on-all

.gitignore

@@ -4,6 +4,7 @@
 .python-version
 .idea/
 .direnv/
+/var/
 
 # ignore roles pulled by ansible-galaxy
 /roles/galaxy/*

.pre-commit-config.yaml

@@ -1,17 +1,16 @@
 ---
-default_install_hook_types: [pre-push]
 
-exclude: "LICENSES/"
+exclude: "^(LICENSES/|var/)"
 
 # See: https://pre-commit.com/hooks.html
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:
-      # - id: check-executables-have-shebangs
       - id: check-added-large-files
       - id: check-case-conflict
       - id: check-json
+      - id: check-shebang-scripts-are-executable
       - id: check-toml
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -24,3 +23,18 @@ repos:
     rev: v6.2.0
     hooks:
       - id: reuse
+  - repo: https://github.com/ansible/ansible-lint
+    rev: v26.3.0
+    hooks:
+      - id: ansible-lint
+        files: '^roles/custom/'
+        args: ['roles/custom']
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: check-examples-vars-migration-version
+        name: Check examples/vars.yml migration version matches expected
+        entry: bin/check-examples-vars-migration-version.sh
+        language: script
+        files: '(examples/vars\.yml|roles/custom/matrix_playbook_migration/defaults/main\.yml)'
+        pass_filenames: false

CHANGELOG.md

@@ -1,3 +1,36 @@
+# 2026-03-23
+
+## Migration validation system introduced
+
+Previously, when updating your setup, you had to remember to read the [CHANGELOG](CHANGELOG.md) file or risk breakage.
+
+Now, the playbook includes a migration validation system that ensures you're aware of breaking changes before they affect your deployment.
+You're now forced to acknowledge each breaking change, unless you wish to live dangerously (see below).
+
+A new `matrix_playbook_migration_validated_version` variable has been introduced.
+
+**New users** who started from the [example `vars.yml`](examples/vars.yml) file already have this variable set and do not need to do anything.
+
+**Existing users** will need to add the following to their `vars.yml` file after reviewing all changelog entries up to now:
+
+```yml
+matrix_playbook_migration_validated_version: v2026.03.23.0
+```
+
+Going forward, whenever a breaking change is introduced the playbook will:
+
+- bump its expected version value (`matrix_playbook_migration_expected_version`), causing a discrepancy with what you validated (`matrix_playbook_migration_validated_version`)
+
+- fail when you run it with a helpful message listing what changed and linking to the relevant changelog entries
+
+After reviewing and adapting your setup, you simply update the variable to the new version.
+
+If you'd like to live dangerously and skip these checks (not recommended), you can set this once and be done with it:
+
+```yml
+matrix_playbook_migration_validated_version: "{{ matrix_playbook_migration_expected_version }}"
+```
+
 # 2026-03-19
 
 ## Matrix Authentication Service now prefers UNIX sockets for playbook-managed Postgres

bin/check-examples-vars-migration-version.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Ensures that the migration validated version in examples/vars.yml
+# matches the expected version in the matrix_playbook_migration role defaults.
+
+set -euo pipefail
+
+defaults_file="roles/custom/matrix_playbook_migration/defaults/main.yml"
+examples_file="examples/vars.yml"
+
+expected_version=$(grep -oP '^matrix_playbook_migration_expected_version:\s*"?\K[^"]+' "$defaults_file")
+examples_version=$(grep -oP '^matrix_playbook_migration_validated_version:\s*"?\K[^"]+' "$examples_file")
+
+if [ -z "$expected_version" ]; then
+	echo "ERROR: Could not extract matrix_playbook_migration_expected_version from $defaults_file"
+	exit 1
+fi
+
+if [ -z "$examples_version" ]; then
+	echo "ERROR: Could not extract matrix_playbook_migration_validated_version from $examples_file"
+	exit 1
+fi
+
+if [ "$expected_version" != "$examples_version" ]; then
+	echo "ERROR: Migration version mismatch!"
+	echo "  $defaults_file has expected version: $expected_version"
+	echo "  $examples_file has validated version: $examples_version"
+	echo ""
+	echo "Please update $examples_file to match."
+	exit 1
+fi

examples/vars.yml

@@ -1,4 +1,9 @@
 ---
+# This variable acknowledges that you've reviewed breaking changes up to this version.
+# The playbook will fail if this is outdated, guiding you through what changed.
+# See the changelog: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md
+matrix_playbook_migration_validated_version: v2026.03.23.0
+
 # The bare domain name which represents your Matrix identity.
 # Matrix user IDs for your server will be of the form (`@alice:example.com`).
 #

flake.nix

@@ -19,6 +19,7 @@
           devShells.default = mkShell {
             buildInputs = [
               just
+              mise
               ansible
             ];
             shellHook = ''

group_vars/matrix_servers

@@ -4909,6 +4909,8 @@ matrix_synapse_experimental_features_msc4108_enabled: "{{ matrix_authentication_
 
 matrix_synapse_experimental_features_msc4140_enabled: "{{ matrix_rtc_enabled }}"
 
+matrix_synapse_experimental_features_msc4143_enabled: "{{ matrix_rtc_enabled }}"
+
 matrix_synapse_experimental_features_msc4222_enabled: "{{ matrix_rtc_enabled }}"
 
 # Disable password authentication when delegating authentication to Matrix Authentication Service.

i18n/requirements.txt

@@ -14,9 +14,9 @@ mdit-py-plugins==0.5.0
 mdurl==0.1.2
 myst-parser==5.0.0
 packaging==26.0
-Pygments==2.19.2
+Pygments==2.20.0
 PyYAML==6.0.3
-requests==2.32.5
+requests==2.33.0
 setuptools==82.0.1
 snowballstemmer==3.0.1
 Sphinx==9.1.0

justfile

@@ -4,6 +4,11 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# mise (dev tool version manager)
+mise_data_dir := env("MISE_DATA_DIR", justfile_directory() / "var/mise")
+mise_trusted_config_paths := justfile_directory() / "mise.toml"
+prek_home := env("PREK_HOME", justfile_directory() / "var/prek")
+
 # Shows help
 default:
     @{{ just_executable() }} --list --justfile "{{ justfile() }}"
@@ -39,9 +44,39 @@ update-playbook-only:
     @git pull -q
     @-git stash pop -q
 
-# Runs ansible-lint against all roles in the playbook
-lint:
-    ansible-lint
+# Invokes mise with the project-local data directory
+mise *args: _ensure_mise_data_directory
+    #!/bin/sh
+    export MISE_DATA_DIR="{{ mise_data_dir }}"
+    export MISE_TRUSTED_CONFIG_PATHS="{{ mise_trusted_config_paths }}"
+    export MISE_YES=1
+    export PREK_HOME="{{ prek_home }}"
+    mise {{ args }}
+
+# Runs prek (pre-commit hooks manager) with the given arguments
+prek *args: _ensure_mise_tools_installed
+    @{{ just_executable() }} --justfile "{{ justfile() }}" mise exec -- prek {{ args }}
+
+# Runs pre-commit hooks on staged files
+prek-run-on-staged *args: _ensure_mise_tools_installed
+    @{{ just_executable() }} --justfile "{{ justfile() }}" prek run {{ args }}
+
+# Runs pre-commit hooks on all files
+prek-run-on-all *args: _ensure_mise_tools_installed
+    @{{ just_executable() }} --justfile "{{ justfile() }}" prek run --all-files {{ args }}
+
+# Installs the git pre-commit hook
+prek-install-git-pre-commit-hook: _ensure_mise_tools_installed
+    #!/usr/bin/env sh
+    set -eu
+    {{ just_executable() }} --justfile "{{ justfile() }}" mise exec -- prek install
+    hook="{{ justfile_directory() }}/.git/hooks/pre-commit"
+    # The installed git hook runs later under Git, outside this just/mise environment.
+    # Injecting PREK_HOME keeps prek's cache under var/prek instead of a global home dir,
+    # which is more predictable and works better in sandboxed tools like Codex/OpenCode.
+    if [ -f "$hook" ] && ! grep -q '^export PREK_HOME=' "$hook"; then
+        sed -i '2iexport PREK_HOME="{{ prek_home }}"' "$hook"
+    fi
 
 # Runs the playbook with --tags=install-all,ensure-matrix-users-created,start and optional arguments
 install-all *extra_args: (run-tags "install-all,ensure-matrix-users-created,start" extra_args)
@@ -84,3 +119,12 @@ stop-group group *extra_args:
 # Rebuilds the mautrix-meta-instagram Ansible role using the mautrix-meta-messenger role as a source
 rebuild-mautrix-meta-instagram:
     /bin/bash "{{ justfile_directory() }}/bin/rebuild-mautrix-meta-instagram.sh" "{{ justfile_directory() }}/roles/custom"
+
+# Internal - ensures var/mise and var/prek directories exist
+_ensure_mise_data_directory:
+    @mkdir -p "{{ mise_data_dir }}"
+    @mkdir -p "{{ prek_home }}"
+
+# Internal - ensures mise tools are installed
+_ensure_mise_tools_installed: _ensure_mise_data_directory
+    @{{ just_executable() }} --justfile "{{ justfile() }}" mise install --quiet

mise.toml

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[tools]
+prek = "0.3.2"
+
+[settings]
+yes = true

requirements.yml

@@ -30,7 +30,7 @@
   version: v2.6.1-3
   name: etherpad
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay.git
-  version: v4.99.1-r0-0-1
+  version: v4.99.1-r0-2-0
   name: exim_relay
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-grafana.git
   version: v11.6.5-9
@@ -45,10 +45,10 @@
   version: v1.9.12-1
   name: livekit_server
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-ntfy.git
-  version: v2.19.2-1
+  version: v2.20.1-0
   name: ntfy
 - src: git+https://github.com/devture/com.devture.ansible.role.playbook_help.git
-  version: 8630e4f1749bcb659c412820f754473f09055052
+  version: ea8c5cc750c4e23d004c9a836dfd9eda82d45ff4
   name: playbook_help
 - src: git+https://github.com/devture/com.devture.ansible.role.playbook_runtime_messages.git
   version: 9b4b088c62b528b73a9a7c93d3109b091dd42ec6
@@ -57,7 +57,7 @@
   version: dd6e15246b7a9a2d921e0b3f9cd8a4a917a1bb2f
   name: playbook_state_preserver
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-postgres.git
-  version: v18.3-1
+  version: v18.3-4
   name: postgres
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-postgres-backup.git
   version: v18-2
@@ -75,7 +75,7 @@
   version: v0.19.1-3
   name: prometheus_postgres_exporter
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-sable.git
-  version: v1.6.0-2
+  version: v1.6.0-3
   name: sable
 - src: git+https://github.com/devture/com.devture.ansible.role.systemd_docker_base.git
   version: v1.5.0-0
@@ -87,7 +87,7 @@
   version: v1.1.0-1
   name: timesync
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik.git
-  version: v3.6.11-2
+  version: v3.6.12-0
   name: traefik
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik-certs-dumper.git
   version: v2.10.0-5

roles/custom/matrix-alertmanager-receiver/defaults/main.yml

@@ -11,7 +11,7 @@
 matrix_alertmanager_receiver_enabled: true
 
 # renovate: datasource=docker depName=docker.io/metio/matrix-alertmanager-receiver
-matrix_alertmanager_receiver_version: 2026.3.18
+matrix_alertmanager_receiver_version: 2026.3.25
 
 matrix_alertmanager_receiver_scheme: https
 

roles/custom/matrix-authentication-service/defaults/main.yml

@@ -22,7 +22,7 @@ matrix_authentication_service_container_repo_version: "{{ 'main' if matrix_authe
 matrix_authentication_service_container_src_files_path: "{{ matrix_base_data_path }}/matrix-authentication-service/container-src"
 
 # renovate: datasource=docker depName=ghcr.io/element-hq/matrix-authentication-service
-matrix_authentication_service_version: 1.13.0
+matrix_authentication_service_version: 1.14.0
 matrix_authentication_service_container_image_registry_prefix: "{{ 'localhost/' if matrix_authentication_service_container_image_self_build else matrix_authentication_service_container_image_registry_prefix_upstream }}"
 matrix_authentication_service_container_image_registry_prefix_upstream: "{{ matrix_authentication_service_container_image_registry_prefix_upstream_default }}"
 matrix_authentication_service_container_image_registry_prefix_upstream_default: "ghcr.io/"

roles/custom/matrix-bot-baibot/defaults/main.yml

@@ -17,7 +17,7 @@ matrix_bot_baibot_container_repo_version: "{{ 'main' if matrix_bot_baibot_versio
 matrix_bot_baibot_container_src_files_path: "{{ matrix_base_data_path }}/baibot/container-src"
 
 # renovate: datasource=docker depName=ghcr.io/etkecc/baibot
-matrix_bot_baibot_version: v1.16.0
+matrix_bot_baibot_version: v1.17.0
 matrix_bot_baibot_container_image: "{{ matrix_bot_baibot_container_image_registry_prefix }}etkecc/baibot:{{ matrix_bot_baibot_version }}"
 matrix_bot_baibot_container_image_registry_prefix: "{{ 'localhost/' if matrix_bot_baibot_container_image_self_build else matrix_bot_baibot_container_image_registry_prefix_upstream }}"
 matrix_bot_baibot_container_image_registry_prefix_upstream: "{{ matrix_bot_baibot_container_image_registry_prefix_upstream_default }}"

roles/custom/matrix-cactus-comments-client/defaults/main.yml

@@ -18,7 +18,7 @@ matrix_cactus_comments_client_public_path: "{{ matrix_cactus_comments_client_bas
 matrix_cactus_comments_client_public_path_file_permissions: "0644"
 
 # renovate: datasource=docker depName=joseluisq/static-web-server
-matrix_cactus_comments_client_version: 2.41.0
+matrix_cactus_comments_client_version: 2.42.0
 
 matrix_cactus_comments_client_container_image: "{{ matrix_cactus_comments_client_container_image_registry_prefix }}joseluisq/static-web-server:{{ matrix_cactus_comments_client_container_image_tag }}"
 matrix_cactus_comments_client_container_image_registry_prefix: "{{ matrix_cactus_comments_client_container_image_registry_prefix_upstream }}"

roles/custom/matrix-client-element/defaults/main.yml

@@ -29,7 +29,7 @@ matrix_client_element_container_image_self_build_repo: "https://github.com/eleme
 matrix_client_element_container_image_self_build_low_memory_system_patch_enabled: "{{ ansible_facts['memtotal_mb'] < 4096 }}"
 
 # renovate: datasource=docker depName=ghcr.io/element-hq/element-web
-matrix_client_element_version: v1.12.12
+matrix_client_element_version: v1.12.13
 
 matrix_client_element_container_image: "{{ matrix_client_element_container_image_registry_prefix }}element-hq/element-web:{{ matrix_client_element_version }}"
 matrix_client_element_container_image_registry_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else matrix_client_element_container_image_registry_prefix_upstream }}"

roles/custom/matrix-client-fluffychat/defaults/main.yml

@@ -13,7 +13,7 @@ matrix_client_fluffychat_container_image_self_build_repo: "https://github.com/et
 matrix_client_fluffychat_container_image_self_build_version: "{{ 'main' if matrix_client_fluffychat_version == 'latest' else matrix_client_fluffychat_version }}"
 
 # renovate: datasource=docker depName=ghcr.io/etkecc/fluffychat-web
-matrix_client_fluffychat_version: v2.4.1
+matrix_client_fluffychat_version: v2.5.1
 matrix_client_fluffychat_container_image: "{{ matrix_client_fluffychat_container_image_registry_prefix }}etkecc/fluffychat-web:{{ matrix_client_fluffychat_version }}"
 matrix_client_fluffychat_container_image_registry_prefix: "{{ 'localhost/' if matrix_client_fluffychat_container_image_self_build else matrix_client_fluffychat_container_image_registry_prefix_upstream }}"
 matrix_client_fluffychat_container_image_registry_prefix_upstream: "{{ matrix_client_fluffychat_container_image_registry_prefix_upstream_default }}"

roles/custom/matrix-continuwuity/defaults/main.yml

@@ -199,6 +199,12 @@ matrix_continuwuity_config_ignore_messages_from_server_names: []
 # Controls the `url_preview_domain_contains_allowlist` setting.
 matrix_continuwuity_config_url_preview_domain_contains_allowlist: []
 
+# Controls the `url_preview_domain_explicit_allowlist` setting.
+matrix_continuwuity_config_url_preview_domain_explicit_allowlist: []
+
+# Controls the `url_preview_check_root_domain` setting.
+matrix_continuwuity_config_url_preview_check_root_domain: false
+
 # Additional environment variables to pass to the container.
 #
 # Environment variables take priority over settings in the configuration file.

roles/custom/matrix-continuwuity/templates/continuwuity.toml.j2

@@ -1319,7 +1319,7 @@ url_preview_domain_contains_allowlist = {{ matrix_continuwuity_config_url_previe
 # attack surface to your server, you are expected to be aware of the risks
 # by doing so.
 #
-#url_preview_domain_explicit_allowlist = []
+url_preview_domain_explicit_allowlist = {{ matrix_continuwuity_config_url_preview_domain_explicit_allowlist | to_json }}
 
 # Vector list of explicit domains not allowed to send requests to for URL
 # previews.
@@ -1359,7 +1359,7 @@ url_preview_domain_contains_allowlist = {{ matrix_continuwuity_config_url_previe
 # allowlist is still too broad for you but you still want to allow all the
 # subdomains under a root domain.
 #
-#url_preview_check_root_domain = false
+url_preview_check_root_domain = {{ matrix_continuwuity_config_url_preview_check_root_domain | to_json }}
 
 # List of forbidden room aliases and room IDs as strings of regex
 # patterns.

roles/custom/matrix-static-files/defaults/main.yml

@@ -13,7 +13,7 @@ matrix_static_files_enabled: true
 matrix_static_files_identifier: matrix-static-files
 
 # renovate: datasource=docker depName=joseluisq/static-web-server
-matrix_static_files_version: 2.41.0
+matrix_static_files_version: 2.42.0
 
 matrix_static_files_base_path: "{{ matrix_base_data_path }}/{{ 'static-files' if matrix_static_files_identifier == 'matrix-static-files' else matrix_static_files_identifier }}"
 matrix_static_files_config_path: "{{ matrix_static_files_base_path }}/config"

roles/custom/matrix-synapse/defaults/main.yml

@@ -16,7 +16,7 @@ matrix_synapse_enabled: true
 matrix_synapse_github_org_and_repo: element-hq/synapse
 
 # renovate: datasource=docker depName=ghcr.io/element-hq/synapse
-matrix_synapse_version: v1.149.1
+matrix_synapse_version: v1.150.0
 
 matrix_synapse_username: ''
 matrix_synapse_uid: ''
@@ -1430,6 +1430,13 @@ matrix_synapse_experimental_features_msc4140_enabled: false
 # See `matrix_synapse_experimental_features_msc4140_enabled`.
 matrix_synapse_max_event_delay_duration: 24h
 
+# Controls whether to enable the MSC4143 experimental feature (RTC transports).
+#
+# This is used by MatrixRTC clients to discover the unstable RTC transports API.
+#
+# See https://github.com/matrix-org/matrix-spec-proposals/pull/4143
+matrix_synapse_experimental_features_msc4143_enabled: false
+
 # Controls whether to enable the MSC4222 experimental feature (adding `state_after` to sync v2).
 #
 # Allow clients to opt-in to a change of the sync v2 API that allows them to correctly track the state of the room.
@@ -1828,7 +1835,7 @@ matrix_synapse_register_user_script_matrix_authentication_service_path: ""
 matrix_synapse_reverse_proxy_companion_enabled: "{{ matrix_synapse_enabled and matrix_synapse_workers_enabled }}"
 
 # renovate: datasource=docker depName=nginx
-matrix_synapse_reverse_proxy_companion_version: 1.29.6-alpine
+matrix_synapse_reverse_proxy_companion_version: 1.29.7-alpine
 
 matrix_synapse_reverse_proxy_companion_base_path: "{{ matrix_synapse_base_path }}/reverse-proxy-companion"
 matrix_synapse_reverse_proxy_companion_confd_path: "{{ matrix_synapse_reverse_proxy_companion_base_path }}/conf.d"

roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2

@@ -3010,6 +3010,9 @@ experimental_features:
   {% if matrix_synapse_experimental_features_msc4140_enabled %}
   msc4140_enabled: true
   {% endif %}
+  {% if matrix_synapse_experimental_features_msc4143_enabled %}
+  msc4143_enabled: true
+  {% endif %}
   {% if matrix_synapse_experimental_features_msc4222_enabled %}
   msc4222_enabled: true
   {% endif %}

roles/custom/matrix_playbook_migration/defaults/main.yml

@@ -1,9 +1,27 @@
-# SPDX-FileCopyrightText: 2023 - 2025 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2023 - 2026 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2024 Suguru Hirahara
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 ---
+
+# The version that the user has validated their setup against.
+# When empty, the user will be prompted to set this variable.
+# New users should set this to the current expected version (see below).
+# See `examples/vars.yml` and `matrix_playbook_migration_expected_version` for the recommended value.
+matrix_playbook_migration_validated_version: ''
+
+# The version that the playbook expects the user to have validated against.
+# This is bumped whenever a breaking change is introduced.
+# The value configured here needs to exist in `matrix_playbook_migration_breaking_changes` as well.
+matrix_playbook_migration_expected_version: "v2026.03.23.0"
+
+# A list of breaking changes, used to inform users what changed between their validated version and the expected version.
+matrix_playbook_migration_breaking_changes:
+  - version: "v2026.03.23.0"
+    summary: "Initial migration validation system"
+    changelog_url: "https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md#2026-03-22"
+
 # Controls if (`matrix_prometheus_nginxlog_exporter` -> `prometheus_nginxlog_exporter`) validation will run.
 matrix_playbook_migration_matrix_prometheus_nginxlog_exporter_migration_validation_enabled: true
 

roles/custom/matrix_playbook_migration/tasks/main.yml

@@ -1,9 +1,14 @@
-# SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2022 - 2026 Slavi Pantaleev
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 ---
 
+- tags:
+    - always
+  block:
+    - ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_migration_version.yml"
+
 - tags:
     - setup-all
     - install-all

roles/custom/matrix_playbook_migration/tasks/validate_migration_version.yml

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Fail if migration version is not validated (first-time onboarding)
+  ansible.builtin.fail:
+    msg: >-
+      This playbook now uses a migration validation system to help you stay aware of breaking changes.
+
+      It appears that you haven't configured the `matrix_playbook_migration_validated_version` variable yet.
+
+      Please review the changelog (https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md)
+      and then add the following to your vars.yml file:
+
+      matrix_playbook_migration_validated_version: {{ matrix_playbook_migration_expected_version }}
+  when: "matrix_playbook_migration_validated_version == ''"
+
+- name: Fail if migration version is outdated
+  ansible.builtin.fail:
+    msg: |-
+      Your validated migration version ({{ matrix_playbook_migration_validated_version }}) is behind the expected version ({{ matrix_playbook_migration_expected_version }}).
+
+      The following breaking changes have been introduced since your last validation:
+
+      {% for item in matrix_playbook_migration_breaking_changes | selectattr('version', '>', matrix_playbook_migration_validated_version) | sort(attribute='version') %}
+      - {{ item.version }}: {{ item.summary }} ({{ item.changelog_url }})
+      {% endfor %}
+
+      After reviewing the above changes and adapting your setup, update your vars.yml:
+
+      matrix_playbook_migration_validated_version: "{{ matrix_playbook_migration_expected_version }}"
+  when: "matrix_playbook_migration_validated_version != '' and matrix_playbook_migration_validated_version < matrix_playbook_migration_expected_version"