Add description field to CI job specification

Release notes

Add optional description field to the CI/CD job specification to allow for documenting jobs.

Problem to solve

User Story: As someone new to a team, I want to be able to understand the team's pipelines as quickly as possible, so I can start adding value sooner rather than later.

Motivation: I recently started with a new team, but have had a hard time understanding all the various pipelines that run in this group of ~300 interrelated projects. Navigating the pipelines in the GitLab UI, and reading through the corresponding .gitlab-ci.yml files, wasn't helping much, though I have plenty of experience with designing sophisticated pipelines in general, and in GitLab CI/CD in particular. Eventually I had to get some people on a video call to walk me through things at a high level, and it turned out much of our team was just as lost as I was, though some had been with the team for years.

This experience would have been significantly different if each pipeline job had a description field. Pipeline creators could use the field to document not just what the job is doing, but why, what its purpose is, how it relates to other jobs in the pipeline, etc. Essentially you could treat it as the documentation that accompanies a function (e.g., docstrings for Python, Doxygen for C++, JavaDoc for Java, etc.). I realize this information could simply be provided in comments in the YAML, but I think there are two good reasons for adding an optional field to the specification:

  1. Having it in the .gitlab-ci.yml keyword reference will make it prominent, and therefore encourage job authors to use it.
  2. The description could be rendered in various places in the GitLab UI, which would benefit users exploring jobs and pipelines via the UI rather than via the YAML files.

Intended users

User experience goal

The user should be able to add something along these lines to their job specifications in the .gitlab-ci.yml file:

hello_world:
  description: |
    Greet the user to ensure they feel welcome.

    Insert more details here.  Potential topics include:
    * Why this job exists.
    * How this job relates to others in the pipeline.
    * Etc.

    It would be great if GitLab could interpret this as [GitLab-flavored
    Markdown](https://docs.gitlab.com/ee/user/markdown.html] and render it
    appropriately when displaying it in the UI.
  stage: greetings
  script:
    - echo "Hello world"

The user would then see the description when viewing the page for an individual job. Possible locations would be:

  1. At the top of the page, immediately above the console log.
  2. In the panel on the right-hand-side of the page, possibly between the job name and the Duration.

In either location, it probably makes sense to display an abbreviated description (e.g., restricted to the first line, or the first N characters), and then provide a means of expanding it to display the full thing (similar to what's done with the ... with commit messages, e.g., when viewing the Commits tab in a MR).

Proposal

Not sure what to put here.

Further details

Permissions and Security

Not sure what to put here.

Documentation

Not sure what to put here.

Availability & Testing

Not sure what to put here.

Available Tier

  • Free

Feature Usage Metrics

Not sure what to put here.

What does success look like, and how can we measure that?

Not sure what to put here.

What is the type of buyer?

Not sure what to put here. By the way, the links in the instructions for this section are broken.

Is this a cross-stage feature?

Not sure what to put here.

What is the competitive advantage or differentiation for this feature?

Not sure what to put here.

Links / references

Not sure what labels to assign.