diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index 1cdbe351c3f67dddedbeb97e1440197cee4b671d..7bb861f1787c59694ab9041aa2bd33835c664682 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -3653,7 +3653,8 @@ variable defined, the [job-level variable takes precedence](../variables/index.m
 
 **Possible inputs**: Variable name and value pairs:
 
-- The name can use only numbers, letters, and underscores (`_`).
+- The name can use only numbers, letters, and underscores (`_`). In some shells,
+  the first character must be a letter.
 - The value must be a string.
 
 **Examples of `variables`:**