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 applicationThis 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_confirmationis stored the same way. - The value is not written to the
descriptioncolumn ofp_ci_builds. Commit statuses use that column, and the commit status API returns it. - The entry method is
job_description, becauseGitlab::Config::Entry::Nodealready has adescriptionaccessor. - 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:
- Structure only: extracts
build_optionsfromYamlProcessor::Result#build_attributes. Without it, adding a key exceeds theMetrics/AbcSizelimit. - Behavior change: adds the keyword, validation, storage, and specs.
- 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
- Resolves #16481
Screenshots or screen recordings
Not applicable. This MR has no UI changes.
How to set up and validate locally
-
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]] -
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)"] -
In a project, commit a
.gitlab-ci.ymlthat usesdescription, and run the pipeline. -
In the Rails console, check the stored job definition and the unchanged
descriptioncolumn: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: addedtrailer. - Documentation:
doc/ci/yaml/_index.mdand the editor schemaci.jsonare updated. - Database: no migrations. The value is stored in the existing
configcolumn and validated byci_job_definition_options.json.