Back in late 2016 I wrote a fragile expect script. It was an attempt to automate certificate renewal for the free Let’s Encrypt service when used with GitLab pages. Let’s just say it sucked and I’m sorry to anyone who ever attempted to use it, let alone those who tried to reach me for support. I couldn’t reproduce their issues. I could fix their bugs. And I generally sucked at responding.
Then the certbot rev’ed (I’m at 0.21.0) and some of the text output changed. It broke the expect script well and truly. That makes for a perfect time to explore a different solution.
After some digging I found the
--manual-auth-hook command line
option for certbot. I don’t know how I missed it before, or whether
it wasn’t there in 0.19.0. Clearly, if I could make a script to be
driven by certbot then I could get away from trying to wrap it in
This resulted in the Radically Simplified Bash Script® to automate publishing certbot authorization files.
The setup for the GitLab CI/CD is the same as before.
There are two pieces of configuration necessary. The first is the
creation of a Certbot
file. It specifies your domains, your email address, and directories
that Certbot will use. Oddly, it seems you can not specify where the
certificates will be stored. That remains under
.ini file below:
text = True domains = [comma delimited list of domains] email = [your email address] renew-by-default agree-tos rsa-key-size = 4096 logs-dir = /Users/andy/tmp/certbot/logs/ work-dir = /Users/andy/tmp/certbot/work/
Note that the
work-dir need to be created and owned
by your user account and not root. The
ssl-renew.ex script does not
run as root, but should be run as the local user..
You will need to modify the
gitlab-auth-hook.sh script to let it know where
various files and directories reside. The values in question are:
SaveDir– Where to save the Let’s Encrypt validation files within your repository.
CertPath– The URI directory where the nounce files will be published and available via HTTP.
$ certbot certonly --config autonomic-guru.ini --manual-auth-hook gitlab-auth-hook.sh --manual --preferred-challenges=http -n --manual-public-ip-logging-ok
This could take a while depending on the number of SANs (domains) in your request and how performant the GitLab CI/CD pipeline is that day. I’ve had this take hours because of GitLab backend issues.
The following is an example output from my last renewal.
$ certbot certonly --config autonomic-guru.ini --manual-auth-hook ./gitlab-auth-hook.sh --manual --preferred-challenges=http -n --manual-public-ip-logging-ok Saving debug log to /Users/u309/tmp/certbot/logs/letsencrypt.log Plugins selected: Authenticator manual, Installer None Renewing an existing certificate Performing the following challenges: http-01 challenge for autonomic.guru http-01 challenge for www.autonomic.guru Waiting for verification... Cleaning up challenges IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/autonomic.guru/fullchain.pem Your key file has been saved at: /etc/letsencrypt/live/autonomic.guru/privkey.pem Your cert will expire on 2018-04-21. To obtain a new or tweaked version of this certificate in the future, simply run certbot again. To non-interactively renew *all* of your certificates, run "certbot renew" - If you like Certbot, please consider supporting our work by: Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate Donating to EFF: https://eff.org/donate-le
As you can see, far more quiet than before. But if the renewal is just sitting there, you might wish to see what’s happening on the GitLap side. In the GitLab project UI, you will be able to see each Certbot validation commit and subsequent CI build.
Updating Your Certs
Sadly, nothing has changed here on the GitLab side. Bring on the manual part.
At this time there is no API call available to add/remove/update a domain in GitLab Pages. Additionally, you can’t update an existing domain to change the certificate.
The process to update is similar to the steps to add the certificates
when you first enabled SSL to your GitLab Pages. Get your certificate
and private key ready (found in
Then steps are:
- Go to the Pages section of the GitLab Project Web UI.
- your domain (I really hate this).
- Add your domain (well, new again).
- Use the
fullchain.pemfor the Certificate text box and
privkey.pemin the Key text box.
- Then click .
- Should only take about a minute or two for the domain and certificate to update and you can confirm it in your browser.
- Make sure you’re working on the branch that GitLab pages will publish on push (typically
- I regularly remove certbot files from the
ledirectory in my repo.
git rm 6jAZH_fKlUQLd_Ar20HtNg4is3DIEjSPIx9p6iF1gGw git commit -a -m "removed file" git push
- GitLab’s CI/CD pipeline doesn’t like empty directories, so I keep at least one file in the
touch place_holder git add place_holder git commit -m "a place holder" place_holder git push