Continuous Deployment using the Serverless Toolkit

If you don't have an existing Serverless Toolkit project yet, follow our Getting Started guide to set up your project.

While you can use the Twilio CLI and @twilio-labs/plugin-serverless in your CI/CD system, it might lead to some conflicts and longer execution times. Instead, if you don't do any other configuration using the Twilio CLI other than twilio serverless commands, we recommend to install twilio-run as a developer dependency in your project.

twilio plugins:install @twilio-labs/plugin-serverless@v2

Important: Make sure the twilio-run version is at least 3.0.0.

Install twilio-run by running inside your project:

npm install --save-dev twilio-run

Most of the configuration that we'll do can be handled through command-line flags, but for convenience we'll use a .twilioserverlessrc configuration file instead. If your project doesn't have one yet, start by creating a .twilioserverlessrc file at the root of your project.

Add the following content to it:

1
{
2
  "commands": {
3
    "deploy": {
4
     /* Your configuration */
5
    }
6
  }
7
}

Anything we specify in the /* Your configuration */ section will now be applied whenever we run twilio-run deploy or twilio serverless:deploy. Alternatively you can scope these configurations to a specific environment or account. Check out our Configuration docs and our guide for working with multiple Twilio accounts for more concrete details on that.

For the purpose of this example we'll only execute deploy from our CI/CD system and hence scope the configuration to the deploy command.

Since twilio-run will not be directly accessible as a command in your CI/CD, make sure your "scripts" section inside the package.json file contains a line such as:

    "deploy": "twilio-run deploy",

This will ensure that you can run npm run deploy which will trigger twilio-run deploy.

By default, the Serverless Toolkit leverages .env files to specify which environment variables should be deployed. However, in your CI/CD system you want to safely store your credentials in the respective secrets store provided by your CI/CD system. Generating a .env file from there can be tedious.

Instead we can use the loadSystemEnv option. If you enable this option you have to specify a "template .env file" through the env option in your configuration. This template file should NOT contain any sensitive information such as secrets. Instead it only lists the keys of the environment variables that should be loaded from the system.

Create a file such as .env.example that only contains the key name of an environment variable that will be present in your CI/CD system. For example:

MY_ENVIRONMENT_VALUE_EXAMPLE=

As long as you make sure that this file does not contain the actual secrets, you can check this file into your version control system such as git.

Then adjust your .twilioserverlessrc file accordingly:

1
{
2
  "commands": {
3
    "deploy": {
4
      "loadSystemEnv": true,
5
      "env": ".env.example"
6
    }
7
  }
8
}

With these changes during deployment twilio-run will take the keys that are in the .env.example (in this example MY_ENVIRONMENT_VALUE_EXAMPLE) and look up the corresponding values in your CI/CD environment to upload the values into your serverless deployment.

Before we can deploy, however, will have to provide credentials for twilio-run to use when deploying your code. While you could provide those by adding ACCOUNT_SID and AUTH_TOKEN keys to the .env.example file and storing those credentials in your environment, the recommended way is to use an API Key and Secret pair for your account as these are easier to rotate in case they get compromised.

Go into the Twilio Console, generate a new pair of API Key and Secret and store these as TWILIO_API_KEY and TWILIO_API_SECRET in the secret storage of your CI/CD system so they get injected into your CI/CD systems environment variables.

Modify your package.json file to update your deploy script to the following:

    "deploy": "twilio-run deploy --username $TWILIO_API_KEY --password $TWILIO_API_SECRET",

This way your credentials are being used to deploy the project but the values themselves are not being uploaded into your deployments environment variables.

Now if you execute npm run deploy it will deploy your project using TWILIO_API_KEY and TWILIO_API_SECRET as credentials. Afterwards it look up the value of the MY_ENVIRONMENT_VALUE_EXAMPLE environment variable on the respective system executing the command and set it as an environment variable on your deployment.

Now that your system is configured you need to update your CI/CD system to:

1. Store the secrets you want to deploy inside the respective secret store of your CI/CD system
2. Make sure they are available as environment variables when your CI/CD system runs
3. Add npm run deploy to the commands executed by your CI/CD system when it is supposed to deploy.