fix: add explicit bool filters for Ansible 12 jinja2_native compatibility (#14963)

* fix: add explicit bool filters for Ansible 12 jinja2_native compatibility

Ansible 12 enables jinja2_native by default, which means string values
like "true"/"false" are no longer automatically coerced to booleans in
when: conditions and Jinja2 if statements. Add | bool filters to all
boolean variable references in tasks, templates, and handlers.

Also reformats long single-line Jinja2 conditionals into multi-line for
readability, fixes GCE default() calls for native mode, adds help
command to the algo script, and updates test fixtures to register the
bool filter.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: add j2lint for Jinja2 template linting

Add j2lint (aristanetworks/j2lint) to catch syntax errors, spacing
issues, and operator formatting in Jinja2 templates. Integrated into
pre-commit hooks, lint.yml CI, and smart-tests.yml.

Rules S3/S5/S6/S7/V1 are ignored — they enforce conventions
incompatible with Ansible's config-file-embedded templates.

Also fixes int+1 → int + 1 operator spacing in server.conf.j2.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: resolve all ansible-lint warnings and enforce zero-tolerance policy

Fix 18 jinja[spacing] errors across 12 files by moving Jinja2 block
delimiters to prevent YAML >- folding from introducing trailing spaces.

Fix 27 key-order[task] warnings across 17 files by reordering task keys
to canonical order (name → when → tags → environment → become → block).

Promote key-order[task] and yaml[line-length] from warn_list to hard
errors by removing warn_list entirely from .ansible-lint.

Add zero-tolerance warning policy to CLAUDE.md explaining why warnings
are unacceptable in a security tool and documenting resolution order.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: dguido

.ansible-lint

@@ -22,10 +22,6 @@ skip_list:
   - 'no-handler'  # Handler usage - some legitimate non-handler use cases
   - 'name[missing]'  # All tasks should be named - 113 issues to fix (temporary)
 
-warn_list:
-  - yaml[line-length]  # Line length - informational only
-  - key-order[task]  # Task key ordering - many existing violations, fix gradually
-
 # Enable additional rules
 enable_list:
   - no-log-password

.github/workflows/lint.yml

@@ -51,6 +51,28 @@ jobs:
       - name: Run yamllint
         run: uv run --with yamllint yamllint -c .yamllint .
 
+  jinja2-lint:
+    name: Jinja2 template linting
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@0c366fd6a839edf440554fa01a7085ccba70ac98  # v5.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup uv environment
+        uses: ./.github/actions/setup-uv
+
+      - name: Run j2lint
+        run: |
+          # Lint Jinja2 templates for syntax and style issues
+          # Ignored rules (incompatible with Ansible config-file templates):
+          #   S3: indentation (dictated by output format, not Jinja style)
+          #   S5: tabs (some config formats require them)
+          #   S6: whitespace-control delimiters ({%- -%} are standard Ansible)
+          #   S7: single-statement-per-line (inline Jinja in config output)
+          #   V1: lowercase variables (existing names like IP_subject_alt_name)
+          uv run --with j2lint j2lint roles/ --ignore S3 S5 S6 S7 V1
+
   python-lint:
     name: Python linting
     runs-on: ubuntu-22.04

.github/workflows/smart-tests.yml

@@ -59,6 +59,7 @@ jobs:
               - '**/*.yml'
               - '**/*.yaml'
               - '**/*.sh'
+              - '**/*.j2'
               - '.ansible-lint'
               - '.yamllint'
               - 'pyproject.toml'
@@ -254,6 +255,11 @@ jobs:
             # Run Ansible linter
             uv run --with ansible-lint ansible-lint
 
+            # Check Jinja2 templates
+            if git diff --name-only "${BASE_SHA}" "${HEAD_SHA}" | grep -q '\.j2$'; then
+              uv run --with j2lint j2lint roles/ --ignore S3 S5 S6 S7 V1
+            fi
+
             # Check shell scripts if any changed
             if git diff --name-only "${BASE_SHA}" "${HEAD_SHA}" | grep -q '\.sh$'; then
               find . -name "*.sh" -type f -not -path "./.git/*" -exec shellcheck {} +

.pre-commit-config.yaml

@@ -53,6 +53,13 @@ repos:
         types: [python]
         pass_filenames: false
 
+      - id: j2lint
+        name: Jinja2 template lint
+        entry: bash -c 'uv run j2lint roles/ --ignore S3 S5 S6 S7 V1'
+        language: system
+        files: '\.j2$'
+        pass_filenames: false
+
       - id: ansible-lint
         name: Ansible-lint
         entry: bash -c 'uv run ansible-lint --force-color || echo "Ansible-lint had issues - check output"'

CLAUDE.md

@@ -67,6 +67,22 @@ Common lint issues to fix before submitting:
 - Jinja2 spacing errors (`{{foo}}` should be `{{ foo }}`)
 - Missing `mode:` on file/directory tasks
 
+### Zero-Tolerance Warning Policy
+
+**No warnings are tolerated in CI.** Every linter finding must be either fixed or explicitly allowlisted in the tool's config file (`.ansible-lint`, `pyproject.toml`, etc.).
+
+Why this matters for Algo:
+- **Security tool** - VPN misconfigurations silently break privacy guarantees. A "cosmetic" warning today hides a real bug tomorrow.
+- **Ansible complexity** - YAML+Jinja2 linting catches real runtime failures (wrong key order breaks `when` evaluation, spacing errors cause template failures). Warnings in Ansible are not style nits.
+- **CI signal integrity** - If 30 warnings scroll by on every run, the 31st one (a real regression) goes unnoticed. Zero warnings means every new finding gets human attention.
+
+Resolution order of preference:
+1. **Fix it** - Preferred. Most findings have straightforward fixes.
+2. **Allowlist in config** - If the rule is wrong for this project, add to `skip_list` with a comment explaining why.
+3. **Inline suppress** - Last resort. Use `# noqa: rule-name` with a comment justifying the exception.
+
+Never use `warn_list` in `.ansible-lint` — it exists as a migration tool, not a permanent home. Rules either pass or are explicitly skipped.
+
 ### Design Requirements
 
 When adding or modifying features, verify these before requesting review:

algo

@@ -160,6 +160,30 @@ fi
 
 # Run the appropriate playbook
 case "$1" in
+  help|-h|--help)
+    echo "Usage: ./algo [COMMAND] [ANSIBLE_OPTIONS]"
+    echo ""
+    echo "Set up a personal VPN in the cloud."
+    echo ""
+    echo "Commands:"
+    echo "  (default)        Deploy a new VPN server"
+    echo "  update-users     Add or remove users on an existing server"
+    echo ""
+    echo "Configuration:"
+    echo "  Edit config.cfg to set users, DNS, and VPN options before deploying."
+    echo ""
+    echo "Non-interactive deployment:"
+    echo "  ./algo -e 'provider=digitalocean server_name=algo region=nyc3 do_token=TOKEN'"
+    echo ""
+    echo "Common Ansible options (passed through):"
+    echo "  -e KEY=VALUE     Set variable (bypass interactive prompts)"
+    echo "  -v, -vvv         Increase output verbosity"
+    echo "  --skip-tags TAG  Skip specific components"
+    echo "  -t, --tags TAG   Run only specific components"
+    echo ""
+    echo "Docs: https://trailofbits.github.io/algo/"
+    exit 0
+    ;;
   update-users)
     uv run ansible-playbook users.yml "${@:2}" -t update-users ;;
   *)

input.yml

@@ -109,22 +109,44 @@
         - name: Set facts based on the input
           set_fact:
             algo_server_name: >-
-              {% if server_name is defined %}{% set _server = server_name %}{%- elif _algo_server_name.user_input is defined and _algo_server_name.user_input | length > 0 -%}
-              {%- set _server = _algo_server_name.user_input -%}
-              {%- else %}{% set _server = defaults['server_name'] %}{% endif -%}
+              {%- if server_name is defined -%}{% set _server = server_name %}{%-
+              elif _algo_server_name.user_input is defined and _algo_server_name.user_input | length > 0 -%}{%-
+              set _server = _algo_server_name.user_input -%}{%-
+              else -%}{% set _server = defaults['server_name'] %}{%-
+              endif -%}
               {{ _server | regex_replace('(?!\.)(\W|_)', '-') }}
             algo_ondemand_cellular: >-
-              {% if ondemand_cellular is defined %}{{ ondemand_cellular | bool }}{%- elif _ondemand_cellular.user_input is defined %}{{ booleans_map[_ondemand_cellular.user_input] | default(defaults['ondemand_cellular']) }}{%- else %}{{ false }}{% endif %}
+              {%- if ondemand_cellular is defined -%}{{ ondemand_cellular | bool }}{%-
+              elif _ondemand_cellular.user_input is defined -%}{{ booleans_map[_ondemand_cellular.user_input] | default(defaults['ondemand_cellular']) }}{%-
+              else -%}{{ false }}{%-
+              endif -%}
             algo_ondemand_wifi: >-
-              {% if ondemand_wifi is defined %}{{ ondemand_wifi | bool }}{%- elif _ondemand_wifi.user_input is defined %}{{ booleans_map[_ondemand_wifi.user_input] | default(defaults['ondemand_wifi']) }}{%- else %}{{ false }}{% endif %}
+              {%- if ondemand_wifi is defined -%}{{ ondemand_wifi | bool }}{%-
+              elif _ondemand_wifi.user_input is defined -%}{{ booleans_map[_ondemand_wifi.user_input] | default(defaults['ondemand_wifi']) }}{%-
+              else -%}{{ false }}{%-
+              endif -%}
             algo_ondemand_wifi_exclude: >-
-              {% if ondemand_wifi_exclude is defined %}{{ ondemand_wifi_exclude | b64encode }}{%- elif _ondemand_wifi_exclude.user_input is defined and _ondemand_wifi_exclude.user_input | length > 0 -%}
-              {{ _ondemand_wifi_exclude.user_input | b64encode }}{%- else %}{{ '_null' | b64encode }}{% endif %}
+              {%- if ondemand_wifi_exclude is defined -%}{{ ondemand_wifi_exclude | b64encode }}{%-
+              elif _ondemand_wifi_exclude.user_input is defined and _ondemand_wifi_exclude.user_input | length > 0 -%}
+              {{ _ondemand_wifi_exclude.user_input | b64encode }}{%-
+              else -%}{{ '_null' | b64encode }}{%-
+              endif -%}
             algo_dns_adblocking: >-
-              {% if dns_adblocking is defined %}{{ dns_adblocking | bool }}{%- elif _dns_adblocking.user_input is defined %}{{ booleans_map[_dns_adblocking.user_input] | default(defaults['dns_adblocking']) }}{%- else %}{{ false }}{% endif %}
+              {%- if dns_adblocking is defined -%}{{ dns_adblocking | bool }}{%-
+              elif _dns_adblocking.user_input is defined -%}{{ booleans_map[_dns_adblocking.user_input] | default(defaults['dns_adblocking']) }}{%-
+              else -%}{{ false }}{%-
+              endif -%}
             algo_ssh_tunneling: >-
-              {% if ssh_tunneling is defined %}{{ ssh_tunneling | bool }}{%- elif _ssh_tunneling.user_input is defined %}{{ booleans_map[_ssh_tunneling.user_input] | default(defaults['ssh_tunneling']) }}{%- else %}{{ false }}{% endif %}
+              {%- if ssh_tunneling is defined -%}{{ ssh_tunneling | bool }}{%-
+              elif _ssh_tunneling.user_input is defined -%}{{ booleans_map[_ssh_tunneling.user_input] | default(defaults['ssh_tunneling']) }}{%-
+              else -%}{{ false }}{%-
+              endif -%}
             algo_store_pki: >-
-              {% if ipsec_enabled %}{%- if store_pki is defined %}{{ store_pki | bool }}{%- elif _store_pki.user_input is defined %}{{ booleans_map[_store_pki.user_input] | default(defaults['store_pki']) }}{%- else %}{{ false }}{% endif %}{% endif %}
+              {%- if ipsec_enabled -%}
+              {%- if store_pki is defined -%}{{ store_pki | bool }}{%-
+              elif _store_pki.user_input is defined -%}{{ booleans_map[_store_pki.user_input] | default(defaults['store_pki']) }}{%-
+              else -%}{{ false }}{%-
+              endif -%}
+              {%- endif -%}
       rescue:
         - include_tasks: playbooks/rescue.yml

pyproject.toml

@@ -119,6 +119,7 @@ dev-dependencies = [
     "ruff>=0.8.0",         # Python linter and formatter
     "yamllint>=1.35.0",    # YAML linter
     "ansible-lint>=24.0.0", # Ansible linter
+    "j2lint>=1.2.0",       # Jinja2 template linter
 ]
 
 [tool.pytest.ini_options]

roles/cloud-azure/tasks/main.yml

@@ -4,7 +4,10 @@
 
 - set_fact:
     algo_region: >-
-      {% if region is defined %}{{ region }}{%- elif _algo_region.user_input %}{{ azure_regions[_algo_region.user_input | int - 1]['name'] }}{%- else %}{{ azure_regions[default_region | int - 1]['name'] }}{% endif %}
+      {%- if region is defined -%}{{ region }}{%-
+      elif _algo_region.user_input -%}{{ azure_regions[_algo_region.user_input | int - 1]['name'] }}{%-
+      else -%}{{ azure_regions[default_region | int - 1]['name'] }}{%-
+      endif -%}
 
 - name: Create AlgoVPN Server
   azure.azcollection.azure_rm_deployment:

roles/cloud-azure/tasks/prompts.yml

@@ -6,7 +6,8 @@
     subscription_id: "{{ azure_subscription_id | default(lookup('env', 'AZURE_SUBSCRIPTION_ID'), true) }}"
   no_log: true
 
-- block:
+- when: region is undefined
+  block:
     - name: Set the default region
       set_fact:
         default_region: >-
@@ -22,4 +23,3 @@
           Enter the number of your desired region
           [{{ default_region }}]
       register: _algo_region
-  when: region is undefined