Serverless Framework Docs


Serverless CI/CD enables you to automatically test and deploy services from Github.


Before you setup your CI/CD workflow, make sure you meet the following requirements:

  1. Deployment Profile must include an AWS Access Role. When Serverless automatically deploys your service, it must be granted permission to your AWS account. This permission is granted by deploying to a stage which has an AWS Access Role configured in it’s deployment profile. This enables Serverless to automatically generate short-lived AWS Access Keys used to authenticate during the deployment. Learn how to setup the AWS Access Role.
  2. Must have your Serverless Framework project checked into Github. Currently only Github is supported as a VCS provider. Your project, including the serverless.yml file, must be checked into the repo.
  3. Must be deployed on AWS. The dashboard currently only supports AWS as a cloud service provider. Other cloud service providers are a work in progress.
  4. Must use the Node runtime. Currently only Serverless Framework projects using the Node runtime are supported. Other runtimes are coming soon.

#Connect to Github

  1. Select your application from the main dashboard.
  2. Select the service you want to deploy or create a new one.
  3. Select the “settings” tab from the application page.
  4. Select the service from the menu under the “SERVICE DEPLOYMENTS” section.
  5. Click the "connect github repository" button to grant the Serverless Dashboard access to the repository.
  6. After authenticate with Github you'll be asked to install the Serverless application in your Github organizations. In the "Repository access" section, ensure you select "All repositories", or that the intended repository is included if you select "Only select repositories".

#Configure the build settings

  1. Select the Github repository from the "repository" dropdown. This must be a repository that contains one more Serverless Framework projects.
  2. Select the "base directory" containing the serverless.yml file. The repository must contain at least one serverless.yml with the org, app, and service values which match the current org/app/service in the dashboard.
  3. Select the “region” for the deployments. Only regions supported by the Serverless Dashboard are currently listed. If you plan to deploy to another region, please reach out sales or support to request support for a new region.

#Branch Deployments

Branch deployments enable you to automatically deploy a service to a stage from a branch in your Github repository.

#Adding a branch deployment

To add a new branch deployment, select the Github branch containing the serverless.yml and the target stage and click "Add". You must click "save settings" at the bottom of the form before the branch deployment is enabled.

#Add a stage to a branch deployment

If you are a first time user, the stage list may be empty. You must first create a new deployment profile, and add the deployment profile to a stage in your application. As mentioned in the requirements section, the deployment profile must also have an AWS Access Role.

#Preview Deployment

Preview deployments enable you to deploy on every pull request. As a part of the pull request review process, it is helpful to have an instance of your serverless application deployed.

#Enabling preview deployments

To enable preview deployments, select "Deploy previews for all branches" or "Deploy previews for individually selected branches". The latter will only deploy a branch from a PR targeting the selected branches.

Each deployment must target a specific stage. You can select a pre-configured stage, or you can select “use branch name as stage”.

#Deleting preview deployments

Configuring the preview deployments with the "use branch name as stages" may lead to a large number of deployed service instances. If those services instances are no longer used, you’ll want to delete them.

Deleted service instance from the dashboard is not yet supported. To delete the service instance you must run sls remove from the CLI in the repository containing the serverless.yml file. The region and stage must also match the region and stage you intend to delete.

#Using branch name as stages

As development teams, we often have multiple pull requests and branches open at once. If we deploy those branches to the same stage then the deployments will override each other.

To avoid this collision, you have the convenient option to "use branch name as stage", which ensures that each pull request will deploy to a unique stage. Since the stage is not preconfigured and may not yet exist at the time of deployment, the default deployment profile will be used. In this case, ensure that the default deployment profile is configured with an AWS Access Role.

If you use the "use branch name as stage", you may also want to reference the branch name in your configuration using Variables. Since the stage name matches the branch name, you can use the ${self:provider.stage} variable in your serverless.yml to reference the stage name, which will match the branch name.

#Running Tests

The Serverless Framework will automatically run tests for each deployment by running npm test. The tests must pass, return 0, before the service is deployed. If the tests fail, then the service will not be deployed.

The tests only run if a test script is present in the package.json file, like in the example below:

  "name": "my-serverless-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  "author": "",
  "license": "ISC"

The tests will be skipped if the npm test command returns Error: no test specified. This is the response from npm if no test script is defined. It is also the default value of the test script when you initialize a new package.json via npm init.

#Custom scripts

Custom scripts before or after a deployment are planned but not yet supported. If this is a requirement for you, please contact sales or support with your requirement.

Custom scripts before or after a test can be set by wrapping your test command in a new script and configuring the test script in package.json to use the wrapper script instead.

#Deployment settings

If your services depends on settings which are different for each stage, we recommend using deployment profiles to set different parameters for each stage.

Have questions?

Head over to the forums to search for your questions and issues or post a new one.