Command-line tool to generate a Let's Encrypt certificate for use with GitLab Pages.
npm install -g gitlab-letsencrypt
Important: To avoid being rate-limited by Let's Encrypt, do not use the
--production option until you have tested everything works OK without it.
gitlab-le will use Let's Encrypt's staging environment, which does not issue real certificates but has very generous rate limits.
gitlab-le \--email email@example.com `# REQUIRED - Let's Encrypt email address` \--domain example.com www.example.com `# REQUIRED - Domain(s) that the cert will be issued for (separated by spaces)` \--repository https://gitlab.com/gitlab_user/gitlab_repo `# REQUIRED - Full URL to your GitLab repository` \--token ... `# REQUIRED - GitLab personal access token, see https://gitlab.com/profile/personal_access_tokens` \--production `# OPTIONAL - Obtain a real certificate instead of a dummy one and configure your repository to use it`--path `# OPTIONAL - Absolute path in your repository where challenge files should be uploaded`--jekyll `# OPTIONAL - Upload challenge files with a Jekyll-compatible YAML front matter` \
gitlab-le --help for more details.
$ gitlab-le --email firstname.lastname@example.org --token ... --domain example.com www.example.com --repository https://example.com/user/my-repo --production By using Let's Encrypt, you are agreeing to the TOS at https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf Uploaded challenge file, waiting for it to be available at http://example.com/.well-known/acme-challenge/35wHSN4YSNjqh5iz5gULxQ4X30cV7vRA_S929uiiNCc Could not find challenge file. Retrying in 30s... Could not find challenge file. Retrying in 1m... Could not find challenge file. Retrying in 2m... Uploaded challenge file, waiting for it to be available at http://www.example.com/.well-known/acme-challenge/50U-eARIh2OYLQN22oe4lib6_ESnwLPhCMMkBlUY1BI Could not find challenge file. Retrying in 30s... Could not find challenge file. Retrying in 1m... Could not find challenge file. Retrying in 2m... Success! Your GitLab page has been configured to use an HTTPS certificate obtained from Let's Encrypt. Try it out: https://example.com https://www.example.com (GitLab might take a few minutes to start using your certificate for the first time) This certificate expires on Sat Apr 14 2018 03:09:06 GMT+0100 (BST). You will need to run gitlab-le again at some time before this date.
How it works
gitlab-le uses the ACME HTTP Challenge to prove ownership of a given set of domains.
- Requests a challenge from Let's Encrypt using the provided email address for the specified domains. One challenge file is generated per domain
- Each challenge file is uploaded to your GitLab repository using GitLab's API, which commits to your repository
- The challenge URL is repeatedly polled until the challenge file is made available. GitLab Pages take a while to update after changes are committed
- If Let's Encrypt was able to verify the challenge file, a certificate for that domain is issued
- Each challenge file is removed from your GitLab repository by committing to it through the GitLab API
--productionwas set, your GitLab page is configured to use the issued certificate
Because Let's Encrypt is a fully automated certificate authority, all issued certificates expire in 90 days.
A fresh certificate can be obtained at any time by running
gitlab-le again, as long as you are within Let's Encrypt's rate limits.
gitlab-le does not save or log anything to disk.
The GitLab access token is used to upload the challenge file to your repository and to delete it once the challenge is completed.
Even though challenge files are deleted from your repository after a challenge is completed, they are still visible in the repository's commit history.
gitlab-le does not rewrite your repository's commit history to hide this.
Challenge files do not have any value to attackers without the RSA keys used to initiate a Let's Encrypt challenge, which are generated on each run of
For more details, refer to the Integrity of Authorizations sections of the ACME specification.
Let's Encrypt certificates expire every 90 days - this is by design to take advantage of automated renewals using ACME. However, GitLab does not provide a way to automatically renew certificates, so this process must be done manually.
Since 10.2, GitLab provides an API to configure HTTPS certificates on a GitLab page, which means
gitlab-le can be configured to obtain new certificates when your existing ones are about to expire.