certbot: Usage, Options & Common CI Errors

certbot issues and renews free Let's Encrypt TLS certificates via ACME.

certbot automates TLS certificates from Let's Encrypt. In CI the dangerous parts are the strict rate limits (which --dry-run / --staging exist to protect) and the challenge requirements that fail in sandboxed runners.

What it does

certbot is the ACME client that obtains, installs, and renews Let's Encrypt certificates. It proves domain control via HTTP-01 (a file under a webroot) or DNS-01 (a TXT record), then writes the cert and key. In automation it is run with certonly and a non-interactive challenge plugin.

Common usage

Terminal

certbot certonly --webroot -w /var/www -d example.com -d www.example.com \
  --email ci@example.com --agree-tos --non-interactive
certbot certonly --dns-cloudflare --dns-cloudflare-credentials cf.ini -d '*.example.com'
certbot certonly --staging -d example.com         # test against staging CA
certbot renew --dry-run                            # simulate renewal safely
certbot certificates                               # list installed certs

Options

Flag	What it does
certonly	Obtain a cert without installing it
--webroot -w <dir>	HTTP-01 challenge via a served directory
--dns-<provider>	DNS-01 challenge plugin (wildcards)
--staging	Use the staging CA (no rate limits)
--dry-run	Test issuance/renewal without saving
--non-interactive --agree-tos	No prompts; accept terms

Common errors in CI

"too many certificates already issued for ... : see https://letsencrypt.org/docs/rate-limits/" - Let's Encrypt limits ~5 duplicate certs/week; ALWAYS develop against --staging or --dry-run, never the production CA. "Timeout during connect (likely firewall problem)" on HTTP-01 means port 80 is not reachable from the internet - sandboxed CI runners usually cannot serve the challenge, so use DNS-01 instead. "unauthorized ... Invalid response from ..." means the challenge file/record was not in place. Missing --non-interactive makes certbot prompt and hang.