Add migration validation system to catch breaking changes early

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/workflows/matrix.yml

@@ -9,37 +9,34 @@ name: Matrix CI
 
 on: [push, pull_request]  # yamllint disable-line rule:truthy
 
-permissions:
-  contents: read
-
 jobs:
-  prek:
+  yamllint:
-    name: Run prek hooks
+    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
     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: Restore prek cache
+      - name: Run ansible-lint
-        uses: actions/cache@v5
+        uses: ansible/ansible-lint@v26.3.0
         with:
-          path: var/prek
+          args: "roles/custom"
-          key: arch-prek-v1-${{ hashFiles('.pre-commit-config.yaml') }}
+          setup_python: "true"
-
+          working_directory: ""
-      - name: Install dependencies
+          requirements_file: requirements.yml
-        run: pacman -S --noconfirm --needed just mise python
+  precommit:
-
+    name: Run pre-commit
-      - name: Run prek hooks
+    runs-on: ubuntu-latest
-        run: |
+    steps:
-          # The checkout action sets safe.directory using its own bundled
+      - name: Checkout code
-          # git, which is separate from the pacman-installed git that prek uses.
+        uses: actions/checkout@v6
-          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - name: Run pre-commit
-          just prek-run-on-all
+        uses: pre-commit/action@v3.0.1

.gitignore

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

.pre-commit-config.yaml

@@ -1,16 +1,17 @@
 ---
+default_install_hook_types: [pre-push]
 
-exclude: "^(LICENSES/|var/)"
+exclude: "LICENSES/"
 
 # 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
@@ -23,18 +24,3 @@ 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,4 +1,4 @@
-# 2026-03-23
+# 2026-03-22
 
 ## Migration validation system introduced
 
@@ -14,9 +14,8 @@ A new `matrix_playbook_migration_validated_version` variable has been introduced
 **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
+matrix_playbook_migration_validated_version: v2026.03.22.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`)

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

@@ -1,35 +0,0 @@
-#!/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

@@ -2,7 +2,7 @@
 # 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
+matrix_playbook_migration_validated_version: v2026.03.22.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,7 +19,6 @@
           devShells.default = mkShell {
             buildInputs = [
               just
-              mise
               ansible
             ];
             shellHook = ''

justfile

@@ -4,11 +4,6 @@
 #
 # 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() }}"
@@ -44,39 +39,9 @@ update-playbook-only:
     @git pull -q
     @-git stash pop -q
 
-# Invokes mise with the project-local data directory
+# Runs ansible-lint against all roles in the playbook
-mise *args: _ensure_mise_data_directory
+lint:
-    #!/bin/sh
+    ansible-lint
-    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)
@@ -119,12 +84,3 @@ 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

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

roles/custom/matrix_playbook_migration/defaults/main.yml

@@ -14,11 +14,11 @@ 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"
+matrix_playbook_migration_expected_version: "v2026.03.22.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"
+  - version: "v2026.03.22.0"
     summary: "Initial migration validation system"
     changelog_url: "https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md#2026-03-22"