Documentation clarification: Environment-scoped variables with rules and include limitation

Summary

The current documentation at https://docs.gitlab.com/ci/environments/#limit-the-environment-scope-of-a-cicd-variable contains a warning added in !133283 (merged):

You should not use environment-scoped variables with rules or include. The variables might not be defined when GitLab validates the pipeline configuration at pipeline creation.

However, testing shows that environment-scoped variables work correctly with include. The limitation may be specific to using them with rules, or when using both rules and include together. The documentation needs clarification.

Background

Original MR: !133283 (merged) (merged October 5, 2023 in GitLab 16.5)

Testing Results

✅ Tested and working: Environment-scoped variables with include
❓ Not tested: Environment-scoped variables with rules
❓ Not tested: Environment-scoped variables with both rules AND include together

The current blanket warning may be preventing users from valid use cases with include.

Questions for Clarification

  1. Does the limitation apply to rules specifically, or to include as well?
  2. Is the issue only when using both rules AND include together?
  3. Has the behavior changed since GitLab 16.5 when this warning was added?

Proposed Documentation Updates

The documentation should be more specific about:

  1. Which keyword(s) are actually problematic (rules, include, or both together)
  2. What works (e.g., "environment-scoped variables work correctly with include")
  3. Why the limitation exists (pipeline validation timing, variable resolution order, etc.)
Edited by Segolene Bouly