Support enriched CI/CD variable description
Release notes
Enriched CI/CD variable descriptions, supporting Markdown and newlines. By having the ability to use Markdown/newlines in CI variable descriptions, it can give a better user experience for developers performing manual pipeline builds by having more detailed descriptions without having to look at raw CI scripts to know more.
Problem to solve
Running manual pipeline events is a powerful feature of GitLab. It provides flexibility for developers to run not only generic manual events but also trigger CI scenarios for certain configuration corner cases and other testing scenarios for a repository. GitLab provides the ability to add descriptions to specific CI variables. This is helpful for users to have pre-populated entries presented at a manual pipeline event.
A limitation to this is that the descriptions of these variables are limited to a simple string. While certain variables a simple string (sentence/paragraph) may suffice, more complex variables may not be able to properly describe how certain values should be used.
variables:
BUILD_MODE:
value: "default"
options:
- "default"
- "minimal"
- "extended"
- "extended-security"
description: "Specify the build mode to perform. (... detail each option)"The above shows an example of a multi-option variable. Developers may a simple line description for a variable, to try to detail each mode in a paragraph that can become long (and not ideally presented). A user about to trigger a build may not be able to easily determine what mode they should prefer to invoke for this event, so they then browse to the raw .gitlab-ci.yml file for a better description of the variable.
If a developer had the means to provide a better description for a CI variable, this could help users avoid the need to view raw CI files.
Intended users
Developer
User experience goal
n/a
Proposal
Developers can already define description entries with raw Markdown/newline content. However, when this content is rendered on a manual pipeline display, it is rendered as a single paragraph string. This proposal would be that the contents used in a variable's description would be passed into rendering logic similar to other Markdown content (e.g. like a repository's README.md file). The resulting rendered content would be presented in the manual pipeline display.
For example, a developer may define this in a pipeline script:
variables:
BUILD_MODE:
value: "default"
options:
- "default"
- "minimal"
- "extended"
- "extended-security"
description: >
Specify the build mode to perform.
The following option allows a user to override the default mode to perform this
job. This can be used be used for R, S or even [T](example-link).
Details of each mode are as follows:
- `default`: This is the default mode.
- `minimal`: Performs a minimal-type of build, disabling options U and I.
- `extended`: An extended mode can help include experimental options that are
not yet part of a build (e.g. the ["W"](w) capability).
- `extended-security`: Same as the extended mode, but we also enable security
options on these extended features.When the pipeline variable is described on a page, the trailing description shows the above text with links to linked content, renders three paragraphs and a bullet list description of the "modes".
Further details
n/a
Permissions and Security
n/a
Documentation
This would ideally require updates to "CI/CD YAML syntax reference"'s variables:description section, providing an example using Markdown/newlines.
Availability & Testing
n/a
Available Tier
All
Feature Usage Metrics
n/a
What does success look like, and how can we measure that?
n/a
What is the type of buyer?
n/a
Is this a cross-stage feature?
n/a
What is the competitive advantage or differentiation for this feature?
n/a