Table of contents

Configuring a continuous integration (CI) tool

A continuous integration (CI) tool deploys software automatically to help you deliver new features without breaking existing functionality.

Examples of CI tools include Jenkins, Travis, Circle, and TeamCity.

Choose CI tool

You should choose a CI tool based on criteria such as:

  • product features
  • support offered
  • pricing
  • security

You should focus on how the tool encrypts and protects any sensitive information or secrets such as keys, usernames or passwords. You are responsible for the assurance of your own services and information.

Configure your CI tool accounts

You should create one or more dedicated PaaS user accounts for use by your CI tool.

Use a different account for each space you want to deploy your app to using your CI tool.

Assign a user role to each of these accounts. These user roles should have the minimum permissions needed for setting up Travis to automatically build and deploy your app.

The GOV.UK PaaS will lock your credentials if your CI tool makes multiple failed login attempts in a short period of time.

Using the Travis CI tool

Assess Travis

Before using the Travis CI tool, you should assess how it encrypts and protects any sensitive information or secrets such as keys, usernames or passwords, and whether it is suitable for your service.

Prerequisites

Before setting up Travis CI, you must have:

  • a Github account
  • admin access to the GitHub repository that hosts your app
  • the latest version of Ruby installed
  • set your app’s name in the app’s manifest.yml file

Set up account

  1. Register for a Travis account.
  2. Link your Travis account to your Github repo.
  3. Select the repositories you want Travis to manage.

Set up Travis using the gem

  1. Clone the GitHub repository that hosts your app to your local machine and navigate to the repository folder.
  2. Run gem install travis --no-rdoc --no-ri to download the gem.
  3. Run the following code to set up Travis:

    travis setup cloudfoundry
    
  4. Input the following information when asked:

    • account username and password
    • the space and organisation to deploy your app to
    • the API endpoint URL: https://api.cloud.service.gov.uk for the Ireland region, or https://api.london.cloud.service.gov.uk for the London region

Travis CI encrypts this information into a .travis.yml file.

You can now build and deploy the app.

Set up Travis manually

  1. Clone the GitHub repository that host your app to your local machine and navigate to the repository folder.
  2. Create a .travis.yml file.
  3. Add the following code to the .travis.yml file:

    deploy:
      edge: true
      provider: cloudfoundry
      username: USERNAME
      api: API_ENDPOINT
      organization: ORGNAME
      space: SPACENAME
    
  4. Run the following to write your encrypted credentials to the .travis.yml:

    travis encrypt --add deploy.password
    

You can now build and deploy the app.

Build and deploy the app

  1. Commit the travis.yml to GitHub. Travis CI uses this file to automatically build and deploy your app.
  2. View your live app at https://NAME.APP_DOMAIN, where:
    • NAME is the name of your app in the manifest.yml file
    • APP_DOMAIN is the domain your app is hosted in

For more information on how to use Travis CI, refer to the Travis CI documentation.

Push an app with Jenkins

There are two main approaches to pushing applications to GOV.UK PaaS with Jenkins:

  1. Use custom scripts (allows full scripting of deployments)
  2. Use the Cloud Foundry plugin for Jenkins (less flexible, relies on application manifest for configuration)

Both approaches require you to set up the credentials plugin first.

Set up dedicated accounts

CI systems should not use normal user accounts. Find out more about configuring your CI tool accounts in PaaS.

Setting up the credentials plugin

To install the credentials plugin manually:

  1. In the Jenkins web interface, click on Manage Jenkins, then Manage Plugins.
  2. Click on the Installed tab and check if “Credentials Plugin” is listed. If it’s listed, skip the next step.
  3. Click on the Available tab and find “Credentials Plugin”. Check the box to select the plugin, then click either Install without restart or Download now and install after restart at the bottom of the interface.

Once the plugin is installed, you will see a Credentials link in the left-hand navigation menu.

Now you can add credentials for the Cloud Foundry user you will be using to push apps from Jenkins.

  1. Click on Credentials, then System. By default, you will see a ‘Global credentials (unrestricted)’ domain. You should set up a different domain for each deployment target/PaaS user account.
  2. Click Add domain and enter a name and description, then click Save.
  3. Click Add credentials and enter the PaaS user account credentials. The kind of credentials is ‘Username with password’, which is typically selected by default.

You can now go on to either:

Setting up custom scripts

Before you set up custom scripts, make sure you first set up the credentials plugin.

Note that using the custom scripts approach exposes the password via the process command line, so it can be read by other processes running on the same machine. If this risk is not acceptable, please use the Cloud Foundry plugin described below. The Cloud Foundry project is aware of the problem and we expect they will provide a more secure login mechanism soon.

The custom scripts approach needs the Jenkins credentials binding plugin. To install it manually:

  1. In the Jenkins web interface, click on Manage Jenkins, then Manage Plugins.
  2. Click on the Available tab and find “Credentials Binding Plugin”. Check the box to select the plugin, then click either Install without restart or Download now and install after restart at the bottom of the interface.
  3. In your build configuration, select the Use secret text(s) or file(s) checkbox in the “Build Environment” section.
  4. Click on the Add drop down menu and select Username and password (separated).
  5. Choose your variable names and select the user whose credentials will be used.

Once this is set up, any shell scripts you configure in Jenkins will have the credentials available as environment variables.

To protect these credentials and prevent them leaking to other Jenkins jobs, we suggest you set your CF_HOME to a temporary directory.

A basic 'execute shell’ buildstep would look like this:

# Set CF_HOME in a temp dir so that jobs do not share or overwrite each others' credentials.
export CF_HOME="$(mktemp -d)"
trap 'rm -r $CF_HOME' EXIT

cf api API_ENDPOINT # https://api.cloud.service.gov.uk for the Ireland region # https://api.london.cloud.service.gov.uk for the London region

# Note: the actual name of the environment variable is determined # by what you enter into the Credentials Binding Plugin cf auth "$CF_USER" "$CF_PASSWORD"

cf target -o myorg -s myspace cf push

# Destroy token cf logout

Setting up the Cloud Foundry Jenkins plugin

Using the Cloud Foundry plugin only allows Jenkins to push your application to GOV.UK PaaS as a post-build action: the equivalent of doing a cf login followed by a cf push. There is little scope for configuration beyond using the application manifest.

Before you do these steps, make sure you first set up the credentials plugin.

To install the Cloud Foundry plugin manually:

  1. In the Jenkins web interface, click on Manage Jenkins, then Manage Plugins.
  2. Click on the Available tab and find “Cloud Foundry Plugin”. Check the box to select the plugin, then click either Install without restart or Download now and install after restart at the bottom of the interface.

An extra post-build action called “Push to Cloud Foundry” is now available in the dropdown menu when you configure a job.

  1. In your job’s configuration, click the Add post-build action dropdown menu and select Push to Cloud Foundry.
  2. In the Target field, enter either https://api.cloud.service.gov.uk for the Ireland region, or https://api.london.cloud.service.gov.uk for the London region.
  3. In Credentials, select the user you created using the credentials plugin.
  4. Enter your organisation and the space the application will be deployed to. See Managing orgs, spaces and users for more details about organisations and spaces. You do not need to tick “Allow self-signed certificate” or “Reset app if already exists”.
  5. The rest of the fields can be left with their default values. The plugin expects you to have a manifest file called manifest.yml in the root of the application folder. If you do not, you can provide the path to the application manifest, or enter a manifest configuration directly into the plugin.
  6. Click Save.

Further information can be found on the Cloud Foundry plugin’s wiki page.