Rate this page:

Continuous Deployment using the Serverless Toolkit

In general the Serverless Toolkit is compatible with any Continuous Integration / Continuous Delivery (CI/CD) system that can install and run Node.js projects. However, some things translate better than others into a CI/CD flow. In this guide we'll cover how you can set up your project to integrate with your CI/CD system. The steps will be independent of any specific CI/CD system but should translate to most major systems.

Project Setup

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

Using the Right Tool

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-run is the core that powers any twilio serverless command but does not come with any additional overhead.

If you do use @twilio-labs/plugin-serverless (twilio serverless) instead of twilio-run, we recommend pinning the version of the plugin to at least the major version you are using. For example for any version 2.x.x:

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

Otherwise you run into the risk of installing the latest version inside your CI/CD system which might result in your flow breaking due to major version changes.

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

Adding Basic Configuration

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:

  "commands": {
    "deploy": {
     /* Your configuration */

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.

Using Environment Variables

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.

Important: You should never check a .env file that contains your credentials into your version control 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:


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:

  "commands": {
    "deploy": {
      "loadSystemEnv": true,
      "env": ".env.example"

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.

Updating your CI/CD flow

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.
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!