certbot: Issue and Test Certs for nginx
certbot obtains and renews TLS certificates from Let's Encrypt, and --dry-run exercises the whole flow against staging without issuing a real cert.
certbot pairs naturally with nginx for automatic HTTPS. In CI you almost always want --dry-run so renewal logic is tested without hitting rate limits or issuing real certs.
What it does
certbot proves control of a domain via an ACME challenge and receives a certificate from Let's Encrypt. The --nginx plugin edits nginx config and reloads it; certonly just fetches the cert and leaves the server config alone. --dry-run runs the full flow against the staging endpoint so nothing is issued for real, which is the safe way to test in CI.
Common usage
# obtain a cert without touching nginx config
certbot certonly --nginx -d example.com -d www.example.com
# test renewal without issuing (CI-safe)
certbot renew --dry-run
# non-interactive issuance
certbot certonly --webroot -w /var/www/html -d example.com \
--non-interactive --agree-tos -m admin@example.comOptions
| Flag | What it does |
|---|---|
| certonly | Obtain the cert only, do not edit server config |
| --nginx | Use the nginx plugin to configure and reload nginx |
| --webroot -w <dir> | Serve the HTTP-01 challenge from a webroot |
| --dry-run | Test against staging without issuing a real cert |
| --non-interactive | Never prompt (required in CI) |
| --agree-tos / -m <email> | Accept the ToS and set the contact email |
In CI
Use certbot renew --dry-run to validate that renewal and the nginx reload hook still work, without consuming issuance rate limits. Always pass --non-interactive so the job never blocks on a prompt. Real issuance belongs on the deploy host, not in a shared CI runner that cannot answer the challenge.
Common errors in CI
The nginx plugin is not working; there may be problems with your existing configuration means nginx -t failed; fix the config first. "Failed authorization procedure ... urn:ietf:params:acme:error:connection" means the ACME server could not reach the challenge, common in CI where the runner is not internet-reachable, so use --dry-run or a DNS challenge. "too many certificates already issued" is a rate limit; use --dry-run or the staging server.