Document quote-wrapping requirement for wildcards in CI rules:changes:
Problem to solve
The current docs state that the possible inputs to rules:
are
- Paths to files. The file paths can include variables. A file path array can also be in
rules:changes:paths
.- Wildcard paths for:
- Single directories, for example
path/to/directory/*
.- A directory and all its subdirectories, for example
path/to/directory/**/*.
- Wildcard glob paths for all files with the same extension or multiple extensions, for example
*.md
orpath/to/directory/*.{rb,py,sh}
.- Wildcard paths to files in the root directory, or all directories, wrapped in double quotes. For example
"*.json"
or"**/*.json"
.
Reading these docs and the items surrounding it, it is not immediately clear (especially from top-level bullet point #3 on that list) that the wildcard glob *.md
is not sufficient on it's own. If a user were to add - *.md
to their changes:
list, they will get an invalid yaml error and may not know how to resolve it.
Proposal
I'd recommend adding a note somewhere that mentions that any wildcards (or really, any string entries that don't start with an alphanumeric character) to the rules:changes:
list need to be wrapped in double quotes to avoid an invalid yaml error. What that looks like exactly is probably better left to a technical writer to avoid clutter, which is why I haven't submitted an MR for this myself.
Other links/references
This issue was previously addressed in gitlab-foss#59540 (closed), but as things changed and docs got rewritten, I think the clarity provided by the original resolution to that issue was lost.
The double quotes limitation was apparent in the MR linked above, but I think in the switch from only:
to rules:
as the primary pipeline logic block, that clarity was lost.