Skip to content

documentation revision for CI pipeline creation

Ben Prescott_ requested to merge bprescott-cirev-20191024 into master

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.

Clarifies that some variables cannot be used in .gitlab-ci.yml

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.

proposed

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

Author's checklist

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

  1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
  2. Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist.
  3. If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by Ben Prescott_

Merge request reports