Link to docs for each error/warning raised during pipeline creation

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Problem

When a pipeline fails to be created because of syntax or semantic errors we display a short plain text message

image

For the user this sometimes is straight forward to understand but most of the time it can be a mystery to solve.

In #216444 (closed) we add support for warning messages to be displayed in the pipeline view or CI Lint page. Warnings may be used to highlight bad practices, incompatible configurations, feature deprecations. Without a proper documentation associated to it it can be hard to manage them. We either return long descriptive warning messages or hard-code a URL documentation. Either of them isn't maintainable. The former introduce knowledge duplication and the latter can't be changed retroactively if the documentation changes.

Solution

Each error message should have a related documentation page for the user to understand how to fix the error, understand the context and find out best practices.

We could introduce a catalog of messages where each entity contains a unique message identifier, URL to documentation, severity (error, warning, etc.), other metadata.

  • code and tests could reference the message ID rather than hard-coded strings. We could improve the message without changing a lot of tests
  • we could update the documentation without impacting code changes and making older error messages up to date with the documentation

Proposal

  • Add a "More information" link next to the error text which will link to the appropriate docs. It should be styled as a text link.
  • We should style the CI Lint link the same way to make it more discoverable.
  • Some error messages have commas and are split onto new lines based on that character. We should remove this logic and instead display the error on one line with the More information link.
image

Messages could be tracked in a YAML file by severity.

# lib/gitlab/ci/messages.yml
job_rules_without_workflow_rules:
  description: Some jobs may allow multiple pipelines to run for a single action
  severity: warning
  reference: path/to/doc/page.md

only_except_deprecation:
  description: `only` and `except` keywords are being deprecated
  severity: warning
  reference: path/to/replace/only/except/with/rules.md

dependency_undefined_in_prior_stages:
  description: Specified dependency was not found in any prior stages
  severity: error
  reference: path/to/doc/page.md

This issue introduces this pattern and applies it for the one warning we currently have, but the follow up (linked) issues apply the pattern to existing errors.

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

Edited by 🤖 GitLab Bot 🤖