Skip to content

Simplify structure of CI/CD variables page

Marcel Amirault requested to merge docs-ci-variables-ctrt-2 into master

What does this MR do?

Simplify the structure of the CI/CD variables page. This MR is mostly shifting things around (again), with very few changes to the content this time, to try to keep it easier to review. The list of changes include:

  • Renamed headers:
    • Protected CI/CD variables -> Protect a CI/CD variable
    • CI/CD variable types -> Use file type CI/CD variables. The majority of this section is talking about File type variables and how to use them. All but one of the crosslinks pointing here were trying to link to file type variable information, (and the other section should have been linking to the top of the page).
    • Expand CI/CD variables -> Prevent CI/CD variable expansion. This is what the task steps are describing.
    • List all environment variables -> List all variables. In the next MR I'll update this language to explain that it's ALL variables, and we don't need to say "environment" here, which is confusing (it's not related to the GitLab "Environments" feature).
    • Use variables in other variables -> Use CI/CD variables in other variables
    • Use the `$` character in variables -> Use the `$` character in CI/CD variables
  • Removed content:
    • Custom variables validated by GitLab. This section was just describing the UI, it's trivially obvious when you see it in the UI.
  • New sections:
    • Troubleshooting: The following three sections are all techniques used for troubleshooting variables in pipelines, and should be listed under a troubleshooting section:
      • List all variables
      • Enable debug logging
      • Restrict access to debug logging
    • Related topics, as per https://docs.gitlab.com/ee/development/documentation/topic_types/#related-topics, we can improve the layout by moving sections that are just crosslinks into Related topics:
      • Auto DevOps environment variables: Now a bullet point, but no copy edits in this MR.
      • Video Walkthrough of a working example: Now a bullet point, but no copy edits in this MR.
  • Moved content:
    • Deployment variables: These are a type of predefined variables, so this content is moved to the predefined variables doc.
    • Limit the environment scope of a CI/CD variable: This section was duplicating a lot of the content already present in the environments doc. A small bit was not duplicated, so I moved this over to the environments doc's section about environment scopes. At the same time, this header was actually the much better name for the topic, so I renamed the other section to this name, and updated the links to that section.
    • CI/CD variable security -> Moved up in the page. Features related to securing the variables now nested under here:
      • Mask a CI/CD variable
      • Protect a CI/CD variable
      • Use file type CI/CD variables

Review app: https://main-ee-108887.docs.gitlab-review.app/ee/ci/variables/

Screenshots

Before After
Screenshot_2023-01-13_at_15.58.31 Screenshot_2023-01-13_at_17.19.36

Related issues

Related to #382363 (closed)

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