In this article we are going to cover Deploy Serverless App with GitHub Actions and AWS SAM.
we will walk through the process of building a serverless application using AWS SAM (Serverless Application Model) and setting up a CI/CD pipeline with GitHub Actions. You’ll learn how to streamline your development workflow by automating deployments, ensuring your serverless applications are built, tested, and deployed efficiently. Whether you’re new to serverless architecture or looking to optimize your CI/CD pipeline, this guide will provide the step-by-step instructions to get you up and running quickly. Let’s dive into creating a seamless, automated deployment pipeline for your serverless application.
Table of Contents
Prerequisites
Before we dive into building the serverless application and setting up the CI/CD pipeline, make sure you have the following prerequisites in place:
- AWS Account: You’ll need an active AWS account to create and manage resources on AWS.
- AWS CLI: Install the AWS Command Line Interface (CLI) on your local machine to interact with AWS services from your terminal.
- AWS SAM CLI: AWS SAM (Serverless Application Model) is a framework that simplifies building and deploying serverless applications.
- GitHub Account: You need a GitHub account to create repositories and use GitHub Actions for CI/CD.
- Git: Install Git on your local machine to interact with GitHub repositories.
- Docker: Docker is required for local testing and deployment of your serverless functions.
- Basic Knowledge of AWS Lambda: Familiarity with AWS Lambda, serverless concepts, and cloud computing would be helpful but is not required.
- Basic Knowledge of GitHub Actions: Familiarity with GitHub Actions workflows and YAML syntax will make the setup process smoother.
Below is the Workflow Diagram:
Install Dependencies packages on Ubuntu 24.04 LTS
Install Docker on Ubuntu 24.04 LTS
sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable --now dockerInstall Unzip on Ubuntu 24.04 LTS
sudo apt install unzipDownload AWS CLI on Ubuntu 24.04 LTS
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/installConfigure AWS CLI on Ubuntu 24.04 LTS
Set up two profiles: dev and prod.
aws configure --profile devProvide your AWS Access Key, Secret Access Key, region, and output format for the development environment.
aws configure --profile prodProvide your AWS Access Key, Secret Access Key, region, and output format for the production environment.
Install AWS SAM CLI on Ubuntu 24.04 LTS
curl -Lo aws-sam-cli-linux-x86_64.zip https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip
unzip aws-sam-cli-linux-x86_64.zip -d sam-installation
sudo ./sam-installation/installSetting Up the Serverless Application
Step #1:Initialize a New AWS SAM Project
Create a Repository in GitHub:
Clone an empty repository and initialize a SAM project:
git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
cd YOUR_REPOSITORY
Set up a fresh AWS SAM project in the repository directory:
sam initSelect the following options:
You can see new files in the repository:
Step #2:Build and Test the Application Locally
sam local invoke -e ./sam-app/events/event.json HelloWorldFunction -t sam-app/template.yaml
You should observe a ‘hello world’ message in the terminal output
Step #3:Set up CI/CD pipeline in GitHub Actions to build and test on GitHub and deploy to AWS
Run this command in the repo directory to create AWS pipeline:
sam pipeline init --bootstrapselect the following options:
root@ip-172-31-42-34:~/aws-sam# sam pipeline init --bootstrap
sam pipeline init generates a pipeline configuration file that your CI/CD system
can use to deploy serverless applications using AWS SAM.
We will guide you through the process to bootstrap resources for each stage,
then walk through the details necessary for creating the pipeline config file.
Please ensure you are in the root folder of your SAM application before you begin.
Select a pipeline template to get started:
1 - AWS Quick Start Pipeline Templates
2 - Custom Pipeline Template Location
Choice: 1
Cloning from https://github.com/aws/aws-sam-cli-pipeline-init-templates.git (process may take a moment)
Select CI/CD system
1 - Jenkins
2 - GitLab CI/CD
3 - GitHub Actions
4 - Bitbucket Pipelines
5 - AWS CodePipeline
Choice: 3
You are using the 2-stage pipeline template.
_________ _________
| | | |
| Stage 1 |->| Stage 2 |
|_________| |_________|
Checking for existing stages...
[!] None detected in this account.
Do you want to go through stage setup process now? If you choose no, you can still reference other bootstrapped resources. [Y/n]: y
For each stage, we will ask for [1] stage definition, [2] account details, and [3]
reference application build resources in order to bootstrap these pipeline
resources.
We recommend using an individual AWS account profiles for each stage in your
pipeline. You can set these profiles up using aws configure or ~/.aws/credentials. See
[https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started-set-up-credentials.html].
Stage 1 Setup
[1] Stage definition
Enter a configuration name for this stage. This will be referenced later when you use the sam pipeline init command:
Stage configuration name: dev
[2] Account details
The following AWS credential sources are available to use.
To know more about configuration AWS credentials, visit the link below:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html
1 - Environment variables (not available)
2 - dev (named profile)
3 - prod (named profile)
q - Quit and configure AWS credentials
Select a credential source to associate with this stage: 2
Associated account 288761735204 with configuration dev.
Enter the region in which you want these resources to be created [us-east-1]: ap-south-1
Select a user permissions provider:
1 - IAM (default)
2 - OpenID Connect (OIDC)
Choice (1, 2): 1
Enter the pipeline IAM user ARN if you have previously created one, or we will create one for you []:
[3] Reference application build resources
Enter the pipeline execution role ARN if you have previously created one, or we will create one for you []:
Enter the CloudFormation execution role ARN if you have previously created one, or we will create one for you []:
Please enter the artifact bucket ARN for your Lambda function. If you do not have a bucket, we will create one for you []:
Does your application contain any IMAGE type Lambda functions? [y/N]: n
[4] Summary
Below is the summary of the answers:
1 - Account: 288761735204
2 - Stage configuration name: dev
3 - Region: ap-south-1
4 - Pipeline user: [to be created]
5 - Pipeline execution role: [to be created]
6 - CloudFormation execution role: [to be created]
7 - Artifacts bucket: [to be created]
8 - ECR image repository: [skipped]
Press enter to confirm the values above, or select an item to edit the value:
This will create the following required resources for the 'dev' configuration:
- Pipeline IAM user
- Pipeline execution role
- CloudFormation execution role
- Artifact bucket
Should we proceed with the creation? [y/N]: y
Creating the required resources...
Successfully created!Record the IAM access key and secret key values of the newly created IAM user (see example output below). These will be needed later for GitHub environment variables. Keep them confidential and do not share them with anyone.
Configure the second stage (production stage) of the pipeline. Choose the options provided below:
Do you want to go through stage setup process now? If you choose no, you can still reference other bootstrapped resources. [Y/n]: y
For each stage, we will ask for [1] stage definition, [2] account details, and [3]
reference application build resources in order to bootstrap these pipeline
resources.
We recommend using an individual AWS account profiles for each stage in your
pipeline. You can set these profiles up using aws configure or ~/.aws/credentials. See
[https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started-set-up-credentials.html].
Stage 2 Setup
[1] Stage definition
Enter a configuration name for this stage. This will be referenced later when you use the sam pipeline init command:
Stage configuration name: prod
[2] Account details
The following AWS credential sources are available to use.
To know more about configuration AWS credentials, visit the link below:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html
1 - Environment variables (not available)
2 - dev (named profile)
3 - prod (named profile)
q - Quit and configure AWS credentials
Select a credential source to associate with this stage: 3
Associated account 288761735204 with configuration prod.
Enter the region in which you want these resources to be created [us-east-1]: ap-south-1
Pipeline IAM user ARN: arn:aws:iam::288761735204:user/aws-sam-cli-managed-dev-pipeline-resou-PipelineUser-8ujby4dlQbIw
[3] Reference application build resources
Enter the pipeline execution role ARN if you have previously created one, or we will create one for you []:
Enter the CloudFormation execution role ARN if you have previously created one, or we will create one for you []:
Please enter the artifact bucket ARN for your Lambda function. If you do not have a bucket, we will create one for you []:
Does your application contain any IMAGE type Lambda functions? [y/N]: n
[4] Summary
Below is the summary of the answers:
1 - Account: 288761735204
2 - Stage configuration name: prod
3 - Region: ap-south-1
4 - Pipeline user ARN: arn:aws:iam::288761735204:user/aws-sam-cli-managed-dev-pipeline-resou-PipelineUser-8ujby4dlQbIw
5 - Pipeline execution role: [to be created]
6 - CloudFormation execution role: [to be created]
7 - Artifacts bucket: [to be created]
8 - ECR image repository: [skipped]
Press enter to confirm the values above, or select an item to edit the value:
This will create the following required resources for the 'prod' configuration:
- Pipeline execution role
- CloudFormation execution role
- Artifact bucket
Should we proceed with the creation? [y/N]: y
Creating the required resources...
Successfully created!
The following resources were created in your account:
- Pipeline execution role
- CloudFormation execution role
- Artifact bucket
View the definition in .aws-sam/pipeline/pipelineconfig.toml,
run sam pipeline bootstrap to generate another set of resources, or proceed to
sam pipeline init to create your pipeline configuration file.
Checking for existing stages...Configuring the CI/CD pipeline will be automatically prompted. Input the values as instructed:
Checking for existing stages...
2 stage(s) were detected, matching the template requirements. If these are incorrect, delete .aws-sam/pipeline/pipelineconfig.toml and rerun
This template configures a pipeline that deploys a serverless application to a testing and a production stage.
What is the GitHub secret name for pipeline user account access key ID? [AWS_ACCESS_KEY_ID]:
What is the GitHub Secret name for pipeline user account access key secret? [AWS_SECRET_ACCESS_KEY]:
What is the git branch used for production deployments? [main]:
What is the template file path? [template.yaml]: sam-app/template.yml
We use the stage configuration name to automatically retrieve the bootstrapped resources created when you ran `sam pipeline bootstrap`.
Here are the stage configuration names detected in .aws-sam/pipeline/pipelineconfig.toml:
1 - dev
2 - prod
Select an index or enter the stage 1's configuration name (as provided during the bootstrapping): 1
What is the sam application stack name for stage 1? [sam-app]: sam-app-dev
Stage 1 configured successfully, configuring stage 2.
Here are the stage configuration names detected in .aws-sam/pipeline/pipelineconfig.toml:
1 - dev
2 - prod
Select an index or enter the stage 2's configuration name (as provided during the bootstrapping): 2
What is the sam application stack name for stage 2? [sam-app]: sam-app-prod
Stage 2 configured successfully.
SUMMARY
We will generate a pipeline config file based on the following information:
Select a user permissions provider.: AWS IAM
What is the GitHub secret name for pipeline user account access key ID?: AWS_ACCESS_KEY_ID
What is the GitHub Secret name for pipeline user account access key secret?: AWS_SECRET_ACCESS_KEY
What is the git branch used for production deployments?: main
What is the template file path?: sam-app/template.yml
Select an index or enter the stage 1's configuration name (as provided during the bootstrapping): 1
What is the sam application stack name for stage 1?: sam-app-dev
What is the pipeline execution role ARN for stage 1?: arn:aws:iam::288761735204:role/aws-sam-cli-managed-dev-pipel-PipelineExecutionRole-GRU3Ilv9CiEb
What is the CloudFormation execution role ARN for stage 1?: arn:aws:iam::288761735204:role/aws-sam-cli-managed-dev-p-CloudFormationExecutionRo-jGmeryXHs3Yk
What is the S3 bucket name for artifacts for stage 1?: aws-sam-cli-managed-dev-pipeline-r-artifactsbucket-4ci1xb8phha6
What is the ECR repository URI for stage 1?:
What is the AWS region for stage 1?: ap-south-1
Select an index or enter the stage 2's configuration name (as provided during the bootstrapping): 2
What is the sam application stack name for stage 2?: sam-app-prod
What is the pipeline execution role ARN for stage 2?: arn:aws:iam::288761735204:role/aws-sam-cli-managed-prod-pipe-PipelineExecutionRole-55AqdPjSlNNg
What is the CloudFormation execution role ARN for stage 2?: arn:aws:iam::288761735204:role/aws-sam-cli-managed-prod--CloudFormationExecutionRo-hG3skHwLvlvk
What is the S3 bucket name for artifacts for stage 2?: aws-sam-cli-managed-prod-pipeline--artifactsbucket-vapolv3rsufd
What is the ECR repository URI for stage 2?:
What is the AWS region for stage 2?: ap-south-1
Successfully created the pipeline configuration file(s):
- .github/workflows/pipeline.yaml
root@ip-172-31-42-34:~/aws-sam#Below is the newly created .github/workflows/pipeline.yml:
name: Pipeline
on:
push:
branches:
- main
- feature*
delete:
branches:
- feature*
env:
SAM_TEMPLATE: sam-app/template.yaml
TESTING_STACK_NAME: sam-app-dev
TESTING_REGION: ap-south-1
TESTING_ARTIFACTS_BUCKET: aws-sam-cli-managed-dev-pipeline-r-artifactsbucket-kru2yty2nfhf
PROD_STACK_NAME: sam-app-prod-2
PROD_REGION: ap-south-1
PROD_ARTIFACTS_BUCKET: aws-sam-cli-managed-prod-pipeline--artifactsbucket-m1dpucifla0y
jobs:
test:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: echo "Running tests..."
delete-feature:
if: github.event_name == 'delete' && startsWith(github.event.ref, 'refs/heads/feature')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: aws-actions/setup-sam@v2
with:
use-installer: true
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ env.TESTING_REGION }}
- name: Delete feature branch stack
run: |
sam delete \
--stack-name $(echo ${GITHUB_REF#refs/heads/} | tr -cd '[a-zA-Z0-9-]') \
--region ${TESTING_REGION} \
--no-prompts
build-and-deploy-feature:
if: startsWith(github.ref, 'refs/heads/feature')
needs: [test]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: aws-actions/setup-sam@v2
with:
use-installer: true
- run: sam build --template ${SAM_TEMPLATE} --use-container
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ env.TESTING_REGION }}
- name: Deploy to feature stack
run: |
sam deploy \
--stack-name $(echo ${GITHUB_REF#refs/heads/} | tr -cd '[a-zA-Z0-9-]') \
--capabilities CAPABILITY_IAM \
--region ${TESTING_REGION} \
--s3-bucket ${TESTING_ARTIFACTS_BUCKET} \
--no-fail-on-empty-changeset
build-and-package:
if: github.ref == 'refs/heads/main'
needs: [test]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: aws-actions/setup-sam@v2
with:
use-installer: true
- run: sam build --template ${SAM_TEMPLATE} --use-container
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ env.TESTING_REGION }}
- name: Upload testing artifacts
run: |
sam package \
--s3-bucket ${TESTING_ARTIFACTS_BUCKET} \
--region ${TESTING_REGION} \
--output-template-file packaged-testing.yaml
- uses: actions/upload-artifact@v4
with:
name: packaged-testing.yaml
path: packaged-testing.yaml
- name: Upload production artifacts
run: |
sam package \
--s3-bucket ${PROD_ARTIFACTS_BUCKET} \
--region ${PROD_REGION} \
--output-template-file packaged-prod.yaml
- uses: actions/upload-artifact@v4
with:
name: packaged-prod.yaml
path: packaged-prod.yaml
deploy-testing:
if: github.ref == 'refs/heads/main'
needs: [build-and-package]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: aws-actions/setup-sam@v2
with:
use-installer: true
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ env.TESTING_REGION }}
- uses: actions/download-artifact@v4
with:
name: packaged-testing.yaml
- name: Deploy to testing account
run: |
sam deploy \
--stack-name ${TESTING_STACK_NAME} \
--template packaged-testing.yaml \
--capabilities CAPABILITY_IAM \
--region ${TESTING_REGION} \
--s3-bucket ${TESTING_ARTIFACTS_BUCKET} \
--no-fail-on-empty-changeset
integration-test:
if: github.ref == 'refs/heads/main'
needs: [deploy-testing]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: echo "Running integration tests..."
deploy-prod:
if: github.ref == 'refs/heads/main'
needs: [integration-test]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: aws-actions/setup-sam@v2
with:
use-installer: true
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ env.PROD_REGION }}
- uses: actions/download-artifact@v4
with:
name: packaged-prod.yaml
- name: Deploy to production account
run: |
sam deploy \
--stack-name ${PROD_STACK_NAME} \
--template packaged-prod.yaml \
--capabilities CAPABILITY_IAM \
--region ${PROD_REGION} \
--s3-bucket ${PROD_ARTIFACTS_BUCKET} \
--no-fail-on-empty-changesetYou can also review the IAM and S3 resources that were created in CloudFormation as a result of the SAM pipeline bootstrap command.
Give the required permissions for the newly created IAM user
Step #4:Configure Secrets in GitHub
Utilize the AWS credentials obtained in Step 3.
- Navigate to your GitHub repository.
- Go to Settings > Secrets and Variables > Actions.
- Add the following secrets:
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY
Step #5:Commit and Push Changes
git add .
git commit -m "Initial commit"
git push origin main
This will trigger the GitHub Actions workflow, automatically deploying your application.
Step #6:Check the CI/CD pipeline in GitHub Actions
Verify the initiation of the CI/CD pipeline process in the ‘Actions’ menu.
Access the URL for the production deployment shown in GitHub Actions CI/CD:
You can also review the deployment details, including the resources created as part of the sam-app-dev and sam-app-prod-2 stacks in CloudFormation:
Remove the resources (four stacks in CloudFormation) if they are no longer needed.
Conclusion:
We successfully built a serverless application with AWS SAM and automated deployments using GitHub Actions. This setup simplifies deployment, improves efficiency, and ensures seamless updates. Enhance it further with monitoring, security, and best practices for a robust CI/CD pipeline.
Conclusion:
We have covered process of building a serverless application using AWS SAM (Serverless Application Model) and setting up a CI/CD pipeline with GitHub Actions.
Related Articles:
Deploy to Kubernetes using GitHub Actions CI/CD, Docker, DockerHub and ArgoCD
Reference:
Using GitHub Actions to deploy serverless applications AWS official page
