Explain pre-filled global variable syntax for .gitlab-ci.yml

Problem to solve

I just tried to use the new pre-filled variables when running pipelines manually feature in GitLab 13.7 (#30101 (closed)), and was pretty confused trying to get it to work. Seems like there's some information missing from the documentation.

  • The doc linked from the feature description merely briefly notes:

    In GitLab 13.7 and later, all global variables with descriptions defined in the .gitlab-ci.yml file are displayed in the variable fields.

  • The CI variables doc linked from there has a section that briefly describes how to define a variable in the CI YAML file:

    variables:
  TEST: "HELLO WORLD"

    and then links to more examples in a similar vein.

  • The section on the variables key in the .gitlab-ci.yml reference similarly only describes variable declarations with a simple value.

It turns out that the actual way to make this work is:

variables:
 TEST:
   value: "some value" # this would be the default value
   description: "This variable makes cakes delicious" # makes this variable appear on the Run Pipeline

but the only place this seems to be explained is #30101 (comment 479537652) and I can't find a reference to this way of defining a variable anywhere in the docs.

Further details

Pretty much this exact issue was predicted in #295649 (closed), but that issue proposes some code changes. In the meantime (and even if that's implemented) some documentation would be very useful.

Proposal

  • Add an explanation of the extended variable syntax to the variables key reference
  • Add an example of the syntax to the CI variables doc along with an explanation that this makes it appear in the run pipeline dialog.

(While I'm at it, why does that doc have both a "Create a custom variable in .gitlab-ci.yml" section and a ".gitlab-ci.yml defined variables" section? They seem redundant.)