Analyze and document expected/supported behavior for matrix variables in rules keywords

Summary

We need to analyze and document the current expected and supported behavior for using matrix variables in various rules: keywords. The current state is unclear and potentially inconsistent.

Problem

As discovered in #578389, there are multiple combinations of matrix variable usage in rules that may or may not work, and it's unclear which behaviors are:

  • Intentional and supported
  • Unintentional but working (and should be supported going forward)
  • Unintentional and should be fixed/blocked

Current Known Behaviors

From testing in #578389:

Working:

  • Matrix variables in rules:changes: - works (example: changes: - $FILE)
  • Matrix variables in rules:if:changes: - works (example: if: $CI_PIPELINE_SOURCE == "merge_request_event" with changes: - $FILE)

Not Working:

  • Matrix variables directly in rules:if: conditions - does not work (briefly worked in 18.5 due to !204549 (merged), reverted in 18.6)

Unknown/Needs Testing:

  • Matrix variables in rules:exists: - should theoretically work due to #411344 (closed) enabling nested expansion, but needs verification
  • Matrix variables with glob patterns (e.g., components/$COMPONENT/**/*) - unclear if this ever worked or should work
  • Combinations of matrix variables with other rule keywords

Root Cause

The current behavior is the result of multiple changes over time:

  • #351764 (closed) changed rules:changes: to use variables_hash_expanded
  • #411344 (closed) enabled nested expansion for rules:exists: in nearly the same way
  • !204549 (merged) briefly enabled matrix variables in rules:if: (18.5 only, reverted in 18.6) the same way

These changes were made independently without a comprehensive view of how matrix variables should work across all rule keywords as none of them intended to impact matrix variable behavior.

Required Actions

  1. Test and document all combinations of matrix variables with rule keywords:

    • rules:if:
    • rules:changes:
    • rules:if:changes:
    • rules:exists:
    • rules:if:exists:
    • With and without glob patterns
    • With and without other variables in the same expression

  2. Decide which behaviors should/have to be officially supported going forward

  3. Document the supported behaviors in:

    • User-facing documentation
    • RSpec tests with clear expectations (not just for what is working, but also for what is NOT working and SHOULD not be working)
    • (Where applicable) Code comments explaining the intended behavior

  4. Update related issues (#363668, #578389, #581340 (closed)) with the official stance on what is and isn't supported

Related Issues

Edited by 🤖 GitLab Bot 🤖