mkcert: Trusted localhost Certificates
mkcert creates a local CA, installs it into the system trust store, and issues certificates that browsers and tools trust without warnings.
mkcert removes the "self-signed cert not trusted" friction in local and CI test servers. Run -install once, then generate certs for whatever hostnames your tests use.
What it does
mkcert -install generates a local CA and adds it to the system (and NSS/Java) trust stores. Running mkcert with hostnames then issues a leaf certificate signed by that CA, with all the given names as SANs.
Common usage
mkcert -install
mkcert localhost 127.0.0.1 ::1
# custom output file names
mkcert -cert-file cert.pem -key-file key.pem example.test localhostOptions
| Flag | What it does |
|---|---|
| -install | Install the local CA into the trust stores |
| -uninstall | Remove the local CA from the trust stores |
| -cert-file <f> -key-file <f> | Output paths for the leaf cert and key |
| -CAROOT | Print the folder holding the local CA (env CAROOT overrides) |
| -client | Generate a client-auth certificate |
In CI
On a runner, set CAROOT to a checked-in or cached CA so every job trusts the same root, then run mkcert -install. For headless jobs the system store is what matters; browser stores are irrelevant unless you run a real browser.
Common errors in CI
"Warning: the local CA is not installed in the system trust store!" means -install could not write to the store, often for lack of privileges; run with the right permissions or set CAROOT to a location the job trusts. "failed to execute update-ca-trust / certutil" means the trust tool is missing from a minimal image; install ca-certificates or libnss3-tools.