update-ca-certificates: Usage, Options & Common CI Errors

update-ca-certificates installs custom CA certs into the system trust store.

When CI sits behind a TLS-intercepting proxy or talks to an internal service with a private CA, every HTTPS call fails until that CA is trusted. update-ca-certificates is how you add it to the OS trust store so curl, git, and language runtimes accept it.

What it does

update-ca-certificates (Debian/Ubuntu/Alpine) regenerates the consolidated CA bundle from the certificates dropped into /usr/local/share/ca-certificates (and /etc/ca-certificates.conf). After it runs, tools that use the system trust store stop reporting "unable to get local issuer certificate" for that CA.

Common usage

Terminal

cp corp-root-ca.crt /usr/local/share/ca-certificates/
update-ca-certificates                 # rebuild the trust store
# Verify it took:
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt server.crt
# RHEL/Fedora equivalent:
cp corp-root-ca.crt /etc/pki/ca-trust/source/anchors/ && update-ca-trust

Options

Step / command	What it does
cp <ca>.crt /usr/local/share/ca-certificates/	Stage a CA (must be .crt, PEM)
update-ca-certificates	Rebuild /etc/ssl/certs bundle
--fresh	Rebuild from scratch, dropping stale links
update-ca-trust (RHEL)	The Red Hat equivalent command

Common errors in CI

The added file MUST end in .crt and be PEM-encoded, or update-ca-certificates ignores it ("0 added") - a .pem or DER file is silently skipped; rename/convert it. Running it does nothing for tools that use their OWN trust store, not the system one: Node respects NODE_EXTRA_CA_CERTS, Python requests uses certifi/REQUESTS_CA_BUNDLE, Java uses its keystore - set those separately. On Alpine you must apk add ca-certificates first or the command is missing. Needs root to write the trust store.