docs: correct how git trusts a private CA bundle

Draft
LA
12h ago
+18-13

Summary

The "Trust a private CA" guide and the git page say that a CA bundle replaces the system trust store for git, and tell customers to append the public root certificates so git can still reach GitHub. Git does not need them: it keeps trusting the system certificates. This PR corrects that, and fixes the startup error quoted in the guide.
Pattern: small update to existing pages, no structural change.

Content changes

  • private-ca.mdx, "How Infrahub resolves the CA bundle": the bundle replaces the system trust store for every component except git. Git trusts the bundle and the certificates installed in the container.
  • private-ca.mdx, Step 1: appending the public root certificates is only needed for services other than Git servers, such as a public SSO provider or webhook endpoint.
  • private-ca.mdx, Step 4: the quoted startup error now matches the real message, and the step describes what the user sees when git does not trust the certificate: the add form shows the error and the repository is not created, and Check connectivity shows the Connection Failed dialog for an existing repository.
  • connect-repository.mdx, "Bundle contents": same correction as the first item.
  • reference/configuration.mdx: regenerated from the tls.ca_bundle field description in backend/infrahub/config.py, which had the same claim.
  • dev/knowledge/backend/tls.md: removes git from the list of clients where the bundle replaces the system store, and explains why.

What needs reviewer attention

All prose in this PR is new. The claims come from a manual test of 1.11.4 with the stock image and a private root plus intermediate CA:

  • Git trusts the system certificates as well as the bundle. With http.sslCAInfo pointing to a bundle that holds only the private CA, git ls-remote https://github.com/opsmill/infrahub from the task worker succeeds. GIT_CURL_VERBOSE=1 shows found 2 certificates in /opt/infrahub/tls/ca-bundle.pem followed by found 450 certificates in /etc/ssl/certs. With -c http.sslCAPath=/nonexistent the same command fails with certificate signer not trusted. The image's git is built on libcurl with GnuTLS, which loads its default CA directory even when a CA file is set.
  • The HTTP client does replace the system store. With the same bundle, a request to https://github.com/ fails with Unable to validate TLS certificate, so the "append the public roots" advice is kept for the other components.
  • Startup error is copied from the container logs and matches backend/infrahub/tls/bundle.py.
  • UI labels (Actions, Check connectivity, Connection Failed, Connectivity Error) are copied from the UI.

What did not change

  • No page moved, no new page, no sidebar change.
  • The Step 4 structure and log checks added in #11090 are kept as they are.
  • The precedence rules, the mount and configuration steps, and the per-component settings are unchanged.

Open issues for the reviewer

  • Git built against OpenSSL. The claim is verified for the stock image (GnuTLS). A custom image where git uses libcurl with OpenSSL may behave differently. Please confirm the docs only need to cover the stock image.
  • Neo4j, Redis, RabbitMQ and S3 were not tested with a bundle that holds only the private CA. The guide keeps the existing statement that the bundle replaces the system store for them.

Verification

  • Vale: 0 errors, 0 warnings on both changed pages.
  • markdownlint did not run locally (not installed in this checkout). It runs in CI.
  • uv run invoke docs.generate-config regenerates reference/configuration.mdx with only the changed sentence.
  • ruff check and ruff format --check pass on backend/infrahub/config.py.
  • npm run build did not run locally. The PR adds no links, so the CI build covers it.

Assisted-by: opsmill-docs-writing-infrahub-docs 0.4.0
Assisted-by: opsmill-dev-pr 0.2.0