Loading
Restructure Operator configuration page and document UID mismatch workarounds
What does this MR do?
Improves docs/configuration/configuring_runner_operator.md in two areas.
Reworked section for helper/build container UID mismatch:
- Renames "Matching helper container and build container user ID and group ID" to "Mismatching user ID and group ID for helper container and build container" so the heading describes the problem rather than one solution. (Only auto-generated
docs-localefiles reference the old anchor; they are regenerated from the source page.) - Restructures the section: it now states up front that the mismatch causes two problems (Git
dubious ownershiperrors, cache permission errors), presents the shared preferred solution (matching UIDs via the build container security context), then documents per-problem workarounds for cases where the build container UID cannot be changed:dubious ownership: configure Git'ssafe.directorywithgit config --global --add safe.directory $CI_PROJECT_DIRinbefore_script. This is safe becauseHOMEmust already point to a writable directory (see the "Overriding theHOMEenvironment variable" section).- Cache permission errors (new content): the OCP helper image archives and extracts cache files as UID
1001, so a non-root build container with a different UID can restore the cache but cannot write to it (Permission denied;chowninbefore_scriptfails since the build user does not own the files). Workaround:chmod -R 777on the cache directory inafter_scriptso permissions preserved in thetararchive make subsequent restores writable by any UID.
Page restructuring to fix incorrect heading nesting:
- Clarifies that the non-root build image requirement applies by default (the
anyuidSCC section describes how to change it). - "Overriding the
HOMEenvironment variable" is no longer nested under "Root vs non-root". - "Watch out for security context constraints", "Run as
anyuidsecurity context constraints", "Mismatching user ID and group ID for helper container and build container", and "Configure SETFCAP" are no longer nested under "Overridinglockedvariable"; they are now standalone troubleshooting entries. - "Using FIPS Compliant GitLab Runner" is moved out of Troubleshooting into its own top-level configuration section (it describes configuration, not an error fix).
- "Register GitLab Runner by using a self-signed certificate" and "Register GitLab Runner with an external URL that points to an IP address" are no longer nested under the FIPS section; they are standalone troubleshooting entries.
- All patch-related sections (Patch structure, Patching the runner pod template, Patching the runner deployment template, Patch order, Examples, Best practices) are grouped under a single new top-level "Patching" section. Heading text is unchanged, so existing anchors (for example,
#patching-the-runner-pod-templatelinked from the Operator properties table) still resolve.
Related issues
Author's checklist
- Optional. Consider taking the GitLab Technical Writing Fundamentals course.
- Follow the:
- If you're adding or changing the main heading of the page (H1), ensure that the product availability details are added.
- If you are a GitLab team member, request a review based on:
- The documentation page's metadata.
- The associated Technical Writer.
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 likeDefault behavior when you close an issue. - The headings (other than the page title) should be active. Instead of
Configuring GDK, say something likeConfigure 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.
- The headings should be something you'd do a Google search for. Instead of
- Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
Edited by Ben Bodenmiller