Skip to content

Update variables table to clarify variable availability

Marcel Amirault requested to merge docs-variables-table-update into master

What does this MR do?

As discussed in the related issue, we need to find a way to make it clearer which variables are available at various stages of pipeline execution, so users can know which ones they can use with each keyword.

This MR explains that there are three types of variables:

  • Pre-pipeline: Available even before the pipeline is attempted to be created. You can use these with config syntax like include to see which files to include.
  • Pipeline: Available when the pipeline is being created, for example useful in job rules: to control which jobs to add to the pipeline.
  • Jobs: Variables only available at the job level, for example used in scripts or other job-level syntax.

This also moves some predefined variables for integrations from a different page over to this page.

Finally, this also removes extra columns from the table which are not useful. In the GitLab and Runner columns, we have lots of old versions, but also many that just say all. Instead, we can drop all the old versions and all, and add any version specific details into the Description column, greatly simplifying the table.

Before:

Variable Defined for GitLab Runner Description
CI_COMMIT_TAG Pipeline 9.0 0.5 The commit tag name. Available only in pipelines for tags.
CI_COMMIT_TAG_MESSAGE Pipeline 15.5 all The commit tag message. Available only in pipelines for tags.
CI_COMMIT_TIMESTAMP Pipeline 13.4 all The timestamp of the commit in the ISO 8601 format. For example, 2022-01-31T16:47:55Z. UTC by default.
CI_COMMIT_TITLE Pipeline 10.8 all The title of the commit. The full first line of the message.
CI_CONCURRENT_ID Jobs only all 11.10 The unique ID of build execution in a single executor.
CI_CONCURRENT_PROJECT_ID Jobs only all 11.10 The unique ID of build execution in a single executor and project.
CI_CONFIG_PATH Pipeline 9.4 0.5 The path to the CI/CD configuration file. Defaults to .gitlab-ci.yml.
CI_DEBUG_TRACE Pipeline all 1.7 true if debug logging (tracing) is enabled.
CI_DEBUG_SERVICES Pipeline 15.7 15.7 true if service container logging is enabled.
CI_DEFAULT_BRANCH Pipeline 12.4 all The name of the project's default branch.

After:

Variable Defined for Description
CI_COMMIT_TAG Pre-pipeline The commit tag name. Available only in pipelines for tags.
CI_COMMIT_TAG_MESSAGE Pre-pipeline The commit tag message. Available only in pipelines for tags. Introduced in GitLab 15.5.
CI_COMMIT_TIMESTAMP Pre-pipeline The timestamp of the commit in the ISO 8601 format. For example, 2022-01-31T16:47:55Z. UTC by default.
CI_COMMIT_TITLE Pre-pipeline The title of the commit. The full first line of the message.
CI_CONCURRENT_ID Jobs only The unique ID of build execution in a single executor.
CI_CONCURRENT_PROJECT_ID Jobs only The unique ID of build execution in a single executor and project.
CI_CONFIG_PATH Pipeline The path to the CI/CD configuration file. Defaults to .gitlab-ci.yml.
CI_DEBUG_TRACE Pipeline true if debug logging (tracing) is enabled.
CI_DEBUG_SERVICES Pipeline true if service container logging is enabled. Introduced in GitLab 15.7. Requires GitLab Runner 15.7.
CI_DEFAULT_BRANCH Pipeline The name of the project's default branch.

Related issues

Related to #467540

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.
Edited by Marcel Amirault

Merge request reports