Travis CI Enterprise SSL Certificate Management

This page contains information relating to SSL certificates and their use in Travis CI Enterprise.

By default, Travis CI Enterprise verifies SSL for all traffic between internal platform components, RabbitMQ, and Github.com/Github Enterprise. SSL verification helps ensure that traffic is delivered securely. It is strongly recommended that you configure your installation with a valid certificate from a trusted authority.

If you have questions about a specific section or have an issue that is not covered then please contact us at enterprise@travis-ci.com for assistance.

Using Self-signed Certificates #

We strongly recommend that you use a valid certificate from a trusted certificate authority when configuring your installation. That said, we recognize that there are various scenarios in which using a self-signed certificate might make more sense for your organization.

In all cases of using self-signed certificates you must disable SSL certificate validation in your settings. This can be done after installation is complete.

After installation you can upload a certificate at any time via the admin dashboard.

Using a trial license #

If you are using a trial license to evaluate Travis CI Enterprise might not make sense to use a trusted certificate. For this scenario we offer the ability to use self-signed certificates that are generated by Travis CI Enterprise itself.

To do this you can select the “Use Self-Signed Cert” option when prompted to provide a custom SSL certificate during installation.

Organizations with an internally managed certificate authority #

Some organizations manage their own internal certificate authority. An internal authority may or may use a root certificate provided by a trusted root authority.

Without a root certificate from a trusted certificate authority #

If your internal certificate authority is not using a root certificate provided by a trusted certificate authority then any certificates produced are considered to be ‘untrusted’ by most tools and browsers, same as a self-signed certificate.

Certificates created by an internal certificate authority can be uploaded during installation in the same way as any other certificate.

Please be aware that you will also need to be sure to follow the instructions on disabling SSL verification below in order to use Travis CI Enterprise.

With a root certificate from a trusted certificate authority #

If your organization’s internal certificate authority does use a root certificate purchased from a trusted certificate authority then the above will not apply. You will not need to disable SSL verification and can proceed as if you are using a certificate directly from a trusted certificate authority.

In some cases it may be necessary to include the intermediate certificate chain in the settings in order for SSL verification to work correctly. The reasons for this can vary depending on your internal setup and your root certificate provider. Please see the section below on how to set intermediate certificate chains for instructions.

Disabling SSL Verification #

SSL verification helps ensure that all traffic between Travis CI Enterprise components is protected. Disabling SSL verification has serious implications!

To disable SSL verification in Travis CI Enterprise:

  1. Log into your dashboard at https://<your-travis-ci-enterprise-domain>:8800.
  2. Click on ‘Settings’ in the topmost menu.
  3. Click ‘Advanced Settings’ in the left menu (or scroll down).
  4. Check the box for ‘Disable SSL cert verification’.
  5. Click ‘Save’ at the bottom of the page. Please note that this will require a restart of Travis CI Enterprise in order to take affect and may cause brief downtime.

This will remove SSL verification checks with internal traffic between Travis CI components. This will also cause all repository hooks created on Github to turn off SSL verification for traffic coming to Travis CI. Please note that this setting will only apply to hooks created after the setting was enabled.

How to add or update certificates after installation #

You can add or update certificates via the admin dashboard at any time after installation.

To upload your certificates:

  1. Log into your dashboard at https://<your-travis-ci-enterprise-domain>:8800.
  2. Click the gear icon on the rightmost side of the top menu and select ‘Console Settings’ from the dropdown.
  3. Click ‘TLS Key & Cert’ in the left menu (or scroll down).
  4. Select the appropriate option depending on the location of your certificate files.
  5. Enter the paths or select the files to upload.
  6. Click ‘Save’ at the bottom of the page. Please note that this will require a restart of Travis CI Enterprise in order to take affect and may cause brief downtime.

A valid x509 certificate and private key files are required. The certificate and key must be in PEM format. The key must be unencrypted.

Using Intermediate Certificate Chains #

In some cases it may be required to provide the intermediate certificate chain for your desired certificate. Reasons for this can vary depending on your internal setup and your root certificate provider.

If you have uploaded a valid certificate but are still seeing unexpected issues related to SSL verification errors then you can set your intermediate cert chain in the settings.

To add your certificate chain:

  1. Log into your dashboard at https://<your-travis-ci-enterprise-domain>:8800.
  2. Click on ‘Settings’ in the topmost menu.
  3. Click ‘Advanced Settings’ in the left menu (or scroll down).
  4. Copy and paste your certificate chain into the text box labeled ‘Custom Certificate Authority (CA) Bundle’.
  5. Click ‘Save’ at the bottom of the page. Please note that this will require a restart of Travis CI Enterprise in order to take affect and may cause brief downtime.

Upon restart you can then verify whether SSL verification is now working. If you are still experiencing trouble even after setting the chain then please contact us at enterprise@travis-ci.com for assistance.

Using a Let’s Encrypt SSL Certificate #

Travis CI Enterprise works well together with a Let’s Encrypt SSL Certificate. To obtain one for your domain, please follow the steps below.

What you need:

  1. An email address Let’s Encrypt can send emails to. This will be used to notify about urgent renewal and security notices.
  2. A domain name under which your installation is available (we’re using travis.example.com in this guide).

Please note: This change will cause downtime for your system,for this reason, we recommend to perform this process in a maintenance window.

To obtain an SSL certificate we’ll be using certbot. Certbot is available as an Ubuntu package.

Please log in to your platform machine via SSH and run the following steps to install certbot:

$ sudo apt-get update
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository ppa:certbot/certbot
$ sudo apt-get update
$ sudo apt-get install certbot

certbot offers multiple ways to obtain a certificate. We’ll pick the temporary webserver option since it doesn’t require any additional configuration. The only prerequisite though is that the Travis CI Enterprise container has to be stopped so that webserver can bind to port 443 properly.

To start, please stop Travis CI Enterprise:

$ replicatedctl app stop

Now, run the following to start the interactive process to obtain the SSL certificate:

$ sudo certbot certonly

It’ll first ask you to pick the authentication method:

How would you like to authenticate with the ACME CA?
-------------------------------------------------------------------------------
1: Spin up a temporary webserver (standalone)
2: Place files in webroot directory (webroot)
-------------------------------------------------------------------------------
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 1

Here, pick 1 and press return.

Then, fill in the aforementioned email address:

Enter email address (used for urgent renewal and security notices) (Enter 'c' to
cancel): ops@example.com

Then, accept the Terms of Services and decide if you’d like to share your email address with the EFF:

-------------------------------------------------------------------------------
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf. You must agree
in order to register with the ACME server at
https://acme-v01.api.letsencrypt.org/directory
-------------------------------------------------------------------------------
(A)gree/(C)ancel: A

-------------------------------------------------------------------------------
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about EFF and
our work to encrypt the web, protect its users and defend digital rights.
-------------------------------------------------------------------------------
(Y)es/(N)o: N

In the last step you’re providing your domain name:

Please enter in your domain name(s) (comma and/or space separated)  (Enter 'c'
to cancel): travis.example.com

After that finished successfully, you’ll see a message similar to the one below:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/travis.example.com/fullchain.pem
   Your key file has been saved at:
   /etc/letsencrypt/live/travis.example.com/privkey.pem
   Your cert will expire on 2018-02-07. 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"

Your certificate has been generated and is now saved on the machine. Please head over to https://travis.example.com:8800/console/settings.

There, in the TLS Key & Cert section, select Server path and fill in the following:

  • SSL Private Key Filename: /etc/letsencrypt/live/travis.example.com/privkey.pem
  • SSL Certificate Filename: /etc/letsencrypt/live/travis.example.com/fullchain.pem

After that, scroll down and click “Save”. After your changes have been saved, you can restart Travis CI Enterprise via:

$ replicatedctl app start

Let’s Encrypt certificates are short-lived, this means they expire after 90 days. This means that you’ll have to renew them on a regular basis. Thankfully this can be done with certbot as well. Run the following commands in order to renew your certificate.

Note: Be aware that this process will also introduce downtime.

$ replicatedctl app stop
$ sudo certbot renew
$ replicatedctl app start

Automate renewal of your Let’s Encrypt SSL Certificate with a cron job #

  1. Create /home/ubuntu/renew-certs.sh containing the following script:

     #!/bin/bash
    
     set -u
    
     function usage() {
       echo
       echo "Usage: $(basename $0)"
       echo
       echo "Simple script to renew certs, should be used via a cron. Assumes that certs are already set up."
       echo
       echo "See https://docs.travis-ci.com/user/enterprise/platform-tips/#use-a-lets-encrypt-ssl-certificate for initial setup info."
       echo
    
       exit 1
     }
    
     if [[ $# -ne 0 ]]; then
       usage
     fi
    
     replicatedctl app stop
     sudo certbot renew
     replicatedctl app start
    
  2. Make the script executable:

     $ chmod +x /home/ubuntu/renew-certs.sh
    
  3. Create a cronjob by editing /etc/crontab and appending the following:

     # Renews certs at 2am on the 1st of February, May, August, and November.
     # Please change the configuration that applies to the certificate you are creating.
     0 2 1 2,5,8,11 * /home/ubuntu/renew-certs.sh
    

    Make sure to adjust the configuration with values that apply to the certificate you are creating.

This process will introduce a small amount of downtime while the certificates are renewed.

Make sure to communicate with your users before each renewal so they are aware that their builds will temporarily be stopped until the certificate gets renewed.