documentation revision for CI pipeline creation
Note: this MR was supereceded: revisions to doc/ci/variables/README.md
were moved to MR 29473
What does this MR do?
A customer raised two tickets (internal: 1, 2) as a result of exploring CI yaml syntax, and directly or indirectly drew attention to some potential improvements in the documentation.
I've got the changes in separate commits, so in principle, I can break this MR up, remove chunks that we don't like, and obviously also take on any suggestions. Happy to do whatever's helpful.
.gitlab-ci.yml
Clarifies that some variables cannot be used in Where variables can be used links to a very technical page.
With my experience I am no more informed which specific variables can be used in .gitlab-ci.yml
during pipeline creation
There's no debugging facility at the pipeline level, so runner debugging is a reasonable way to see what variables are set to. But some are created by the runner, or at some other point. I can't document this definitively, for all executors, so I also documented a way to make sure a variable is available. ie: Folk shouldn't just assume.
I arrived at this list by brute force testing everything visible in a shell runner.
Environment variables expressions
Using variables in pipeline creation logic is documented for only/except, which is now deprecated syntax.
No need to fully document rules in that location, because the main rules syntax docs include variable examples. So, have revised it to make rules the first class citizen in that part of the docs, but an only/except
example remains documented in that location because it doesn't seem to make sense to overhaul only/except
docs.
This is one of a number of gaps where rules
isn't documented a fully.
Pattern matching against a variable
Documentation currently a single sentence. I opened an issue for this.
Separate section
- So it doesn't bloat the previous section, and
- It applies to conjunction/disjunction as well.
The bug is a significant complication here.
I struggled to find an example regex that I could get to work: at least one customer has spent a lot of time trying different incantations in their .gitlab-ci.yml
and assumed it was just lack of documentation.
By clearly documenting it, folk won't spend more time trying to make it work, and we're being transparent about the feature's current limitation.
If merged, I'll update the bug issue to request the docs are updated once it's fixed.
Conjunction / Disjunction
A customer thought referring to Ruby docs was unfriendly, and a group of support engineers who swarmed on this ticket did not agree on how the precedence works.
It's a small change to document it in our own docs, fundamentally using the same language, which I think is clear enough.
I wanted to provide an example to illustrate it. Getting them to behave differently the other way round was doable, because I found a bug
Really small update as I can't think of an example that proves it.
Related issues
- https://gitlab.com/bprescott_/todo/issues/48
- https://gitlab.com/gitlab-com/support/docs/issues/13
- #36942 (closed)
Author's checklist
-
Workflow -
Follow the Documentation Guidelines and Style Guide. -
If applicable, update the permissions table. -
Link docs to and from the higher-level index page, plus other related docs where helpful. -
Apply the documentation label.
Review checklist
All reviewers can help ensure accuracy, clarity, completeness, and adherence to the Documentation Guidelines and Style Guide.
1. Primary Reviewer
-
Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.
2. Technical Writer
-
Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable DevOps stage.
3. Maintainer
-
Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review. -
Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist. -
If there has not been a technical writer review, create an issue for one using the Doc Review template.