Add description keyword to CI job configuration

What does this MR do and why?

Adds an optional description keyword to CI/CD jobs and trigger jobs. A job name is usually too short to explain what a job is for. The keyword accepts a string of up to 128 characters.

rspec:
  script: bundle exec rspec
  description: Unit tests for the application

This MR only stores the value. Showing it to users is left for follow-up MRs:

  • GraphQL: expose the value on CiJob.
  • Job details page: show the value in the UI.

How the value is stored:

  • The value goes into options[:description] of the job definition (p_ci_job_definitions). manual_confirmation is stored the same way.
  • The value is not written to the description column of p_ci_builds. Commit statuses use that column, and the commit status API returns it.
  • The entry method is job_description, because Gitlab::Config::Entry::Node already has a description accessor.
  • A blank value ('' or whitespace only) is valid but not stored. This avoids extra job definitions.
  • Jobs without a description get the same job definition checksum as before, so deploying creates no new definitions.
  • The description is part of the job definition. It is lost after the pipeline is archived. This is documented.
  • default: does not accept the keyword.

The MR has three commits:

  1. Structure only: extracts build_options from YamlProcessor::Result#build_attributes. Without it, adding a key exceeds the Metrics/AbcSize limit.
  2. Behavior change: adds the keyword, validation, storage, and specs.
  3. Documentation: YAML reference and pipeline editor schema.

I did not add a feature flag. The change stores a value only, and nothing reads it yet.

References

Screenshots or screen recordings

Not applicable. This MR has no UI changes.

How to set up and validate locally

  1. In the Rails console, parse a configuration with the new keyword:

    yaml = <<~YAML
      rspec:
        script: echo
        description: Unit tests for the application
      blank:
        script: echo
        description: ''
    YAML
    
    builds = Gitlab::Ci::YamlProcessor.new(yaml).execute.builds
    builds.map { |b| [b[:name], b[:options][:description]] }
    # => [["rspec", "Unit tests for the application"], ["blank", nil]]
  2. Parse a configuration with a description longer than 128 characters:

    Gitlab::Ci::YamlProcessor.new("rspec:\n  script: echo\n  description: #{'a' * 129}").execute.errors
    # => ["jobs:rspec job description is too long (maximum is 128 characters)"]
  3. In a project, commit a .gitlab-ci.yml that uses description, and run the pipeline.

  4. In the Rails console, check the stored job definition and the unchanged description column:

    build = Ci::Build.last
    build.job_definition.config[:options][:description] # => "Unit tests for the application"
    build.description                                   # => nil

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

  • Changelog: the behavior commit has a Changelog: added trailer.
  • Documentation: doc/ci/yaml/_index.md and the editor schema ci.json are updated.
  • Database: no migrations. The value is stored in the existing config column and validated by ci_job_definition_options.json.

Merge request reports

Loading
Loading