PR #11090 - opsmill/infrahub

Summary

Adds a troubleshooting entry for repositories that fail certificate verification because the task worker could not write its git configuration file. Adds Kubernetes commands to the git TLS checks. Pattern: smaller update to two existing pages.

What changed

git-integration/connect-repository.mdx, "Troubleshoot repository connections": new entry, "Repository fails certificate verification with a CA bundle configured". It states:
- the symptom: SSL verification failed for <repository>, please validate the certificate chain. while INFRAHUB_TLS_CA_BUNDLE or INFRAHUB_GIT_TLS_CA_FILE is set;
- the cause: the task worker cannot write the file named by INFRAHUB_GIT_GLOBAL_CONFIG_FILE, logs one error per setting and continues to start;
- how to find the error in the log with Docker Compose and Kubernetes;
- the fix: point INFRAHUB_GIT_GLOBAL_CONFIG_FILE at a writable path, with a Helm emptyDir example.
deploy-manage/install-configure/production-deployment/private-ca.mdx, step 4: the restart and checks are now in Docker Compose, Docker and Helm tabs, in the same installation-method tab group as steps 2 and 3. The log search also looks for could not lock config file and links to the new entry.
connect-repository.mdx, the two validation blocks for "Connecting to a Git server with a private CA" and "Disabling certificate verification": the checks read ${INFRAHUB_GIT_GLOBAL_CONFIG_FILE:-/opt/infrahub/.gitconfig} instead of a fixed /opt/infrahub/.gitconfig. With a fixed path, the check reads the wrong file when the setting points somewhere else. The "Disabling certificate verification" block also has the kubectl exec form.

Facts checked against the implementation

The task worker sets GIT_CONFIG_GLOBAL to git.global_config_file and writes user.name, user.email, safe.directory, credential.usehttppath, credential.helper, then the TLS keys, at each startup: backend/infrahub/workers/infrahub_async.py:304-318.
A failed write is logged as Failed to set git <key>: <git stderr> and does not stop startup: backend/infrahub/git/global_config.py:42.
Git's stderr when it cannot write the file is error: could not lock config file <path>: Permission denied. This was reproduced locally with GIT_CONFIG_GLOBAL pointing into a read-only directory.
The repository error text: backend/infrahub/git/base.py:1210.
Deployment name <fullname>-infrahub-task-worker and label service=infrahub-task-worker: charts/infrahub/templates/infrahub-task-worker.yaml:5-8. For a release named infrahub, fullname is infrahub: _helpers.tpl.

What needs reviewer attention

The emptyDir example mounts at /opt/infrahub/gitconfig. The task worker creates the parent directory if it is missing (infrahub_async.py:307-309). Kubernetes creates emptyDir volumes with mode 0777, so the example relies on that for any user.
kubectl logs -l <selector> returns only the last 10 lines per pod by default. The commands pass --tail=-1 so that the startup lines are included.
The Helm helm upgrade command uses the community chart reference. Enterprise users substitute their chart, as stated in the sentence before it.

Out of scope

Installation on OpenShift. The infrahub-enterprise chart has a values.openshift.yaml overlay that sets a writable home directory and INFRAHUB_GIT_GLOBAL_CONFIG_FILE (opsmill/infrahub-helm#101). Documenting it on the install page is left for a later change.
Product changes: making /opt/infrahub writable by group 0 in the image, and making the task worker fail at startup when it cannot write its git configuration file. These are not docs changes.

Verification

Vale: 0 errors, 0 warnings on the 2 changed files.
markdownlint-cli2: 0 errors on the 2 changed files.
Word check (simple, simply, easy, easily, just) on added lines: no matches.
npm run build in docs/: passed, with onBrokenLinks and onBrokenAnchors set to throw, so the new anchors resolve.
Subject-verb review of the 35 new or rewritten sentences and 6 non-technical verbs: 2 sentences rewritten.

🤖 Generated with Claude Code