Deploy NestJS to AWS Serverless with GitHub Actions

This guide will walk you through deploying a NestJS application to AWS Lambda using serverless framework, configuring environment variables, setting up AWS credentials, and using AWS Systems Manager Parameter Store for secure configuration management.

📋Prerequisites

•NestJS application ready for deployment
•AWS account with appropriate permissions
•GitHub repository for your NestJS project
•Node.js and npm/yarn installed locally
•Serverless Framework CLI installed globally: npm install -g serverless

1Create AWS IAM User and Access Keys

a) Create IAM User

Log in to AWS Console and navigate to IAM → Users
Click Create User
Enter a username (e.g., github-actions-deployer)
Select Provide user access to the AWS Management Console (optional) or Programmatic access
Click Next

b) Attach Permissions

Attach the following policies (for production, create a custom policy with minimal required permissions):

AmazonS3FullAccess (or specific bucket access)

AWSLambda_FullAccess

IAMFullAccess (or create/update role permissions)

CloudFormationFullAccess

AmazonAPIGatewayAdministrator

CloudWatchFullAccess

AmazonSSMFullAccess (for Parameter Store)

Security Note: For production, create custom IAM policies with only the minimum required permissions instead of using full access policies.

c) Create Access Keys

After creating the user, go to the Security credentials tab
Click Create access key
Select Application running outside AWS as the use case
Download or copy both the Access Key ID and Secret Access Key

⚠️ Important: Save these credentials securely. The Secret Access Key cannot be retrieved again if lost.

2Configure Environment Variables in Parameter Store

a) Access AWS Systems Manager Parameter Store

Navigate to AWS Console → Systems Manager → Parameter Store
Click Create parameter

b) Create Parameters

For each environment variable, create a parameter with the following structure:

Example Parameters:

•Name: /nestjs/prod/DATABASE_URL
Type: SecureString
Value: Your database connection string
•Name: /nestjs/prod/JWT_SECRET
Type: SecureString
Value: Your JWT secret key
•Name: /nestjs/prod/API_KEY
Type: SecureString
Value: Your API key
•Name: /nestjs/prod/NODE_ENV
Type: String
Value: production

# Using AWS CLI (alternative method)

aws ssm put-parameter \

--name "/nestjs/prod/DATABASE_URL" \

--type "SecureString" \

--value "postgresql://user:password@host:5432/dbname"

c) Parameter Naming Convention

Use a hierarchical naming structure:

/<application-name>/<environment>/<parameter-name>

Examples:

•/nestjs/prod/ - Production environment
•/nestjs/staging/ - Staging environment
•/nestjs/dev/ - Development environment

3Setup Serverless Framework in NestJS Project

a) Install Serverless Plugin for NestJS

Install required packages:

npm install --save-dev serverless serverless-offline

npm install @vendia/serverless-express

b) Create serverless.yml

Create serverless.yml in your project root:

service: nestjs-app

frameworkVersion: '3'

provider:

runtime: nodejs18.x

region: us-east-1

stage: ${opt:stage, 'dev'}

environment:

NODE_ENV: ${ssm:/nestjs/${self:provider.stage}/NODE_ENV}

DATABASE_URL: ${ssm:/nestjs/${self:provider.stage}/DATABASE_URL~true}

JWT_SECRET: ${ssm:/nestjs/${self:provider.stage}/JWT_SECRET~true}

API_KEY: ${ssm:/nestjs/${self:provider.stage}/API_KEY~true}

iam:

role:

statements:

- Effect: Allow

Action:

- ssm:GetParameter

- ssm:GetParameters

- ssm:GetParametersByPath

Resource:

- arn:aws:ssm:${self:provider.region}:*:parameter/nestjs/${self:provider.stage}/*

functions:

api:

handler: dist/lambda.handler

events:

- http:

path: /{proxy+}

method: ANY

cors: true

- http:

path: /

method: ANY

cors: true

plugins:

- serverless-offline

Note: The ~true suffix decrypts SecureString parameters. Make sure your Lambda execution role has permissions to access SSM Parameter Store.

c) Create Lambda Handler

Create src/lambda.ts:

import { NestFactory } from '@nestjs/core';

import { ExpressAdapter } from '@nestjs/platform-express';

import serverlessExpress from '@vendia/serverless-express';

import express from 'express';

import { AppModule } from './app.module';

let cachedServer: any;

async function bootstrap() {

if (!cachedServer) {

const expressApp = express();

const nestApp = await NestFactory.create(AppModule, new ExpressAdapter(expressApp));

nestApp.enableCors();

await nestApp.init();

cachedServer = serverlessExpress({ app: expressApp });

}

return cachedServer;

}

export const handler = async (event: any, context: any) => {

const server = await bootstrap();

return server(event, context);

};

d) Update tsconfig.json

Ensure your tsconfig.json compiles to dist folder:

{

"compilerOptions": {

"outDir": "./dist",

// ... other options

}

4Setup GitHub Secrets

a) Add AWS Credentials to GitHub

Go to your GitHub repository
Navigate to Settings → Secrets and variables → Actions
Click New repository secret
Add the following secrets:

Secrets to add:

•Name: AWS_ACCESS_KEY_ID
Value: Your AWS Access Key ID
•Name: AWS_SECRET_ACCESS_KEY
Value: Your AWS Secret Access Key
•Name: AWS_REGION
Value: us-east-1 (or your preferred region)

Security Best Practice: Never commit AWS credentials to your repository. Always use GitHub Secrets for sensitive information.

5Create GitHub Actions Workflow

a) Create Workflow File

Create .github/workflows/deploy.yml:

on:

push:

branches:

- main

workflow_dispatch:

jobs:

deploy:

runs-on: ubuntu-latest

steps:

- name: Checkout code

uses: actions/checkout@v3

- name: Setup Node.js

uses: actions/setup-node@v3

with:

node-version: '18.x'

- name: Install dependencies

run: npm ci

- name: Build application

run: npm run build

- name: Configure AWS credentials

uses: aws-actions/configure-aws-credentials@v2

with:

aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}

aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

aws-region: ${{ secrets.AWS_REGION }}

- name: Install Serverless Framework

run: npm install -g serverless

- name: Deploy to AWS Lambda

run: serverless deploy --stage prod

Note: Modify the --stage parameter to match your environment (prod, staging, dev). The workflow will automatically fetch environment variables from Parameter Store based on the stage.

b) Environment-Specific Deployments

For multiple environments, you can use matrix strategy or branch-based deployment:

# Example: Deploy based on branch

on:

push:

branches:

- main

- staging

- develop

jobs:

deploy:

runs-on: ubuntu-latest

steps:

# ... previous steps ...

- name: Deploy to AWS Lambda

run: |

if [[ "$GITHUB_REF" == "refs/heads/main" ]]; then

serverless deploy --stage prod

elif [[ "$GITHUB_REF" == "refs/heads/staging" ]]; then

serverless deploy --stage staging

else

serverless deploy --stage dev

6Test the Deployment

After deployment, test your API:

# The deployment will output an API Gateway URL

curl https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/

✅ Your NestJS application is now deployed to AWS Lambda and accessible via API Gateway!

🔧Troubleshooting

Common Issues:

Parameter Store Access Denied: Ensure your Lambda execution role has ssm:GetParameterpermissions for the Parameter Store path used in your serverless.yml.
Build Failures: Make sure all dependencies are listed in package.jsonand use npm ci instead of npm installfor consistent builds.
Cold Start Issues: Consider using provisioned concurrency or optimizing your NestJS application startup time.
Timeout Errors: Increase the Lambda timeout in serverless.yml(default is 6 seconds, max is 900 seconds).

📚Additional Resources

Deploy NestJS to AWS Serverless with GitHub Actions

📋Prerequisites

•NestJS application ready for deployment
•AWS account with appropriate permissions
•GitHub repository for your NestJS project
•Node.js and npm/yarn installed locally
•Serverless Framework CLI installed globally: npm install -g serverless

1Create AWS IAM User and Access Keys

a) Create IAM User

Log in to AWS Console and navigate to IAM → Users
Click Create User
Enter a username (e.g., github-actions-deployer)
Select Provide user access to the AWS Management Console (optional) or Programmatic access
Click Next

b) Attach Permissions

Attach the following policies (for production, create a custom policy with minimal required permissions):

AmazonS3FullAccess (or specific bucket access)

AWSLambda_FullAccess

IAMFullAccess (or create/update role permissions)

CloudFormationFullAccess

AmazonAPIGatewayAdministrator

CloudWatchFullAccess

AmazonSSMFullAccess (for Parameter Store)

Security Note: For production, create custom IAM policies with only the minimum required permissions instead of using full access policies.

c) Create Access Keys

After creating the user, go to the Security credentials tab
Click Create access key
Select Application running outside AWS as the use case
Download or copy both the Access Key ID and Secret Access Key

⚠️ Important: Save these credentials securely. The Secret Access Key cannot be retrieved again if lost.

2Configure Environment Variables in Parameter Store

a) Access AWS Systems Manager Parameter Store

Navigate to AWS Console → Systems Manager → Parameter Store
Click Create parameter

b) Create Parameters

For each environment variable, create a parameter with the following structure:

Example Parameters:

•Name: /nestjs/prod/DATABASE_URL
Type: SecureString
Value: Your database connection string
•Name: /nestjs/prod/JWT_SECRET
Type: SecureString
Value: Your JWT secret key
•Name: /nestjs/prod/API_KEY
Type: SecureString
Value: Your API key
•Name: /nestjs/prod/NODE_ENV
Type: String
Value: production

# Using AWS CLI (alternative method)

aws ssm put-parameter \

--name "/nestjs/prod/DATABASE_URL" \

--type "SecureString" \

--value "postgresql://user:password@host:5432/dbname"

c) Parameter Naming Convention

Use a hierarchical naming structure:

/<application-name>/<environment>/<parameter-name>

Examples:

•/nestjs/prod/ - Production environment
•/nestjs/staging/ - Staging environment
•/nestjs/dev/ - Development environment

3Setup Serverless Framework in NestJS Project

a) Install Serverless Plugin for NestJS

Install required packages:

npm install --save-dev serverless serverless-offline

npm install @vendia/serverless-express

b) Create serverless.yml

Create serverless.yml in your project root:

service: nestjs-app

frameworkVersion: '3'

provider:

runtime: nodejs18.x

region: us-east-1

stage: ${opt:stage, 'dev'}

environment:

NODE_ENV: ${ssm:/nestjs/${self:provider.stage}/NODE_ENV}

DATABASE_URL: ${ssm:/nestjs/${self:provider.stage}/DATABASE_URL~true}

JWT_SECRET: ${ssm:/nestjs/${self:provider.stage}/JWT_SECRET~true}

API_KEY: ${ssm:/nestjs/${self:provider.stage}/API_KEY~true}

iam:

role:

statements:

- Effect: Allow

Action:

- ssm:GetParameter

- ssm:GetParameters

- ssm:GetParametersByPath

Resource:

- arn:aws:ssm:${self:provider.region}:*:parameter/nestjs/${self:provider.stage}/*

functions:

api:

handler: dist/lambda.handler

events:

- http:

path: /{proxy+}

method: ANY

cors: true

- http:

path: /

method: ANY

cors: true

plugins:

- serverless-offline

Note: The ~true suffix decrypts SecureString parameters. Make sure your Lambda execution role has permissions to access SSM Parameter Store.

c) Create Lambda Handler

Create src/lambda.ts:

import { NestFactory } from '@nestjs/core';

import { ExpressAdapter } from '@nestjs/platform-express';

import serverlessExpress from '@vendia/serverless-express';

import express from 'express';

import { AppModule } from './app.module';

let cachedServer: any;

async function bootstrap() {

if (!cachedServer) {

const expressApp = express();

const nestApp = await NestFactory.create(AppModule, new ExpressAdapter(expressApp));

nestApp.enableCors();

await nestApp.init();

cachedServer = serverlessExpress({ app: expressApp });

}

return cachedServer;

}

export const handler = async (event: any, context: any) => {

const server = await bootstrap();

return server(event, context);

};

d) Update tsconfig.json

Ensure your tsconfig.json compiles to dist folder:

{

"compilerOptions": {

"outDir": "./dist",

// ... other options

}

4Setup GitHub Secrets

a) Add AWS Credentials to GitHub

Go to your GitHub repository
Navigate to Settings → Secrets and variables → Actions
Click New repository secret
Add the following secrets:

Secrets to add:

•Name: AWS_ACCESS_KEY_ID
Value: Your AWS Access Key ID
•Name: AWS_SECRET_ACCESS_KEY
Value: Your AWS Secret Access Key
•Name: AWS_REGION
Value: us-east-1 (or your preferred region)

Security Best Practice: Never commit AWS credentials to your repository. Always use GitHub Secrets for sensitive information.

5Create GitHub Actions Workflow

a) Create Workflow File

Create .github/workflows/deploy.yml:

on:

push:

branches:

- main

workflow_dispatch:

jobs:

deploy:

runs-on: ubuntu-latest

steps:

- name: Checkout code

uses: actions/checkout@v3

- name: Setup Node.js

uses: actions/setup-node@v3

with:

node-version: '18.x'

- name: Install dependencies

run: npm ci

- name: Build application

run: npm run build

- name: Configure AWS credentials

uses: aws-actions/configure-aws-credentials@v2

with:

aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}

aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

aws-region: ${{ secrets.AWS_REGION }}

- name: Install Serverless Framework

run: npm install -g serverless

- name: Deploy to AWS Lambda

run: serverless deploy --stage prod

Note: Modify the --stage parameter to match your environment (prod, staging, dev). The workflow will automatically fetch environment variables from Parameter Store based on the stage.

b) Environment-Specific Deployments

For multiple environments, you can use matrix strategy or branch-based deployment:

# Example: Deploy based on branch

on:

push:

branches:

- main

- staging

- develop

jobs:

deploy:

runs-on: ubuntu-latest

steps:

# ... previous steps ...

- name: Deploy to AWS Lambda

run: |

if [[ "$GITHUB_REF" == "refs/heads/main" ]]; then

serverless deploy --stage prod

elif [[ "$GITHUB_REF" == "refs/heads/staging" ]]; then

serverless deploy --stage staging

else

serverless deploy --stage dev

6Test the Deployment

After deployment, test your API:

# The deployment will output an API Gateway URL

curl https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/

✅ Your NestJS application is now deployed to AWS Lambda and accessible via API Gateway!

🔧Troubleshooting

Common Issues:

Parameter Store Access Denied: Ensure your Lambda execution role has ssm:GetParameterpermissions for the Parameter Store path used in your serverless.yml.
Build Failures: Make sure all dependencies are listed in package.jsonand use npm ci instead of npm installfor consistent builds.
Cold Start Issues: Consider using provisioned concurrency or optimizing your NestJS application startup time.
Timeout Errors: Increase the Lambda timeout in serverless.yml(default is 6 seconds, max is 900 seconds).