Multi-Account AWS SAM Deployments with GitLab CI/CD


The AWS Serverless Application Model (SAM) is a robust framework that enables developers to define, deploy, and manage serverless applications. With the rise of serverless computing, continuous integration and delivery (CI/CD) has become increasingly important in the development process. GitLab CI/CD is an excellent tool for automating application deployment workflows, making it an ideal choice for working with AWS SAM.

This article will discuss setting up multi-account AWS SAM deployments using GitLab CI/CD. We’ll cover everything from setting up cross-account IAM roles for authorization to deploying your application using CloudFormation. By the end of this article, you will have a solid understanding of configuring your GitLab CI/CD pipeline for the seamless deployment of your serverless applications.

Multi-Account AWS Deployments

When working with AWS, it’s essential to establish security boundaries by creating separate accounts for different environments, such as development, staging, and production. This approach mitigates the risk of accidentally affecting production resources during development or testing.

To set up cross-account IAM roles for authorization, follow these steps:

  1. Establish AWS accounts: Create individual accounts for development, staging, and production deployments. This will help maintain a separation of concerns between environments.
  2. Set up GitLab IAM roles: Within each account, create an IAM role that allows GitLab access to the required services, such as Lambda functions, API Gateway, DynamoDB, and S3 buckets.
  3. Create an S3 bucket for CI artifacts: In one of the accounts (typically the shared services account), create an S3 bucket to store artifacts generated during the CI/CD process.
  4. Assume SharedServiceRole: Before making cross-account AWS calls, ensure that GitLab assumes the SharedServiceRole in your pipeline configuration. This allows GitLab to access resources in other accounts securely.

Single Deployment Pipeline

In GitLab CI/CD, the .gitlab-ci.yml file defines the pipeline’s structure and logic. The pipeline consists of multiple stages that control your application’s deployment process flow.

Testing Stage

Unit tests and dependency scans are executed against your code during testing. This helps ensure your application is free of vulnerabilities and performs as expected before being deployed to an environment.

Build Stage

In the build stage, your SAM template and code are packaged for deployment using the aws cloudformation package CLI command. This process generates an artifact containing all required resources for deployment, such as Lambda functions, API Gateway configurations, and DynamoDB tables.

Deploy Stage

The deployment stage uses AWS CloudFormation to deploy the packaged application in a target environment. You can configure this stage to wait for manual confirmation before releasing the code into production. This provides an added layer of safety by allowing you to review changes before they go live.


Here’s an example of a .gitlab-ci.yml the file that demonstrates how to set up a GitLab CI/CD pipeline for testing, building, and deploying an AWS SAM application:

image: node:14

  AWS_REGION: us-east-1
  S3_BUCKET: my-sam-deployment-bucket
  STACK_NAME: my-sam-application

  - test
  - build
  - deploy

# Testing Stage
  stage: test
    - npm ci
    - npm run test

# Build Stage
  stage: build
    - npm install -g aws-sam-cli
    - sam build --use-container
    - sam package --output-template-file packaged.yaml --s3-bucket $S3_BUCKET
      - packaged.yaml

# Deploy Stages (to different environments)
.deploy_template: &deploy_definition
  stage: deploy
    - aws cloudformation deploy --template-file packaged.yaml --stack-name $STACK_NAME --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND

  <<: *deploy_definition
      - develop # Replace with your development branch name

  <<: *deploy_definition
    name: staging
    url: <> # Replace with your staging environment URL
  when: manual
      - staging # Replace with your staging branch name

  <<: *deploy_definition
    name: production
    url: <> # Replace with your production environment URL
  when: manual
      - main # Replace with your main branch name or master

This example demonstrates a GitLab CI/CD pipeline with three stages: test, build, and deploy. It performs unit tests in the testing stage, builds and packages the AWS SAM application in the build stage, and deploys to different environments (development, staging, and production) in the deployment stage.

In this example, deploying staging and production environments requires manual approval. Replace the branch names, environment URLs, and other variables according to your project’s requirements.

Dynamic Feature Branch Deployments and Review Apps

Dynamic feature branch deployments enable parallel development by allowing developers to work on separate branches without affecting the main codebase. GitLab CI/CD supports this workflow by providing Review Apps that let you view an instance of your application during code review.

To implement dynamic feature branch deployments, specify an environment in your file as part of a deployment job. This allows GitLab to track deployed environments automatically and associate them with specific branches.

Additionally, you can use the on_stop property in your pipeline configuration to define a job that shuts down environments when they are no longer needed. This helps conserve resources and minimize costs associated with idle deployments.

Integrations and Demo

GitLab CI/CD offers numerous integration capabilities to enhance your AWS SAM deployment process. This section will demonstrate how to set up a GitLab CI/CD pipeline for AWS SAM deployments and discuss best practices for integrating GitLab CI/CD with AWS SAM.

  1. Create a GitLab project: Begin by creating a new GitLab project to host your AWS SAM application code and pipeline configuration.
  2. Configure AWS credentials: Add your AWS access and secret access keys as environment variables in your GitLab project settings. This allows your pipeline to authenticate with AWS services securely.
  3. Define your pipeline: Create a .gitlab-ci.yml file in the root directory of your project and define the stages, jobs, and environment-specific configurations for testing, building, and deploying your application.
  4. Test your pipeline: Commit and push changes to your repository to trigger the pipeline. Monitor the pipeline’s progress in the GitLab interface and ensure that all stages complete successfully.
  5. Review deployed application: If you’ve configured Review Apps, you can view a live instance of your application during code review. This helps streamline the review process by providing visual feedback on how changes will affect the application once deployed.

By following these steps and best practices, you can create a robust GitLab CI/CD pipeline for deploying your AWS SAM applications across multiple environments securely and efficiently.

User Stories

To further illustrate the benefits of using GitLab CI/CD for AWS SAM deployments, let’s explore some real-world examples:

User Story 1: E-commerce Platform

An e-commerce platform company wanted to leverage the power of serverless architecture to build a highly scalable and cost-effective solution for its growing customer base. They chose AWS SAM as their serverless framework and GitLab for their CI/CD pipeline.

By integrating GitLab CI/CD with AWS SAM, the development team could quickly iterate on new features and deploy updates without downtime. They created separate AWS accounts for development, staging, and production environments, enhancing security and making it easier to manage resources.

With the help of dynamic feature branch deployments and Review Apps, the team streamlined their code review process, enabling them to catch bugs more efficiently before they reached production. Additionally, they could easily roll back changes or deploy hotfixes when needed.

Using GitLab CI/CD for AWS SAM deployments helped the e-commerce platform reduce deployment times, improve code quality, and enhance collaboration among its development team.

User Story 2: HealthTech Startup

A health tech startup developed a serverless application using AWS SAM to handle patient data processing and analysis. The sensitive nature of the data required stringent security measures and a reliable deployment process. The startup chose GitLab CI/CD as its deployment solution.

They maintained strict security boundaries around their sensitive data by setting up multi-account AWS deployments with separate accounts for development, staging, and production environments. Cross-account IAM roles ensured that only authorized personnel could access specific resources within each account.

Furthermore, the single deployment pipeline offered by GitLab CI/CD allowed them to seamlessly automate testing, building, and deploying their application. With manual confirmation before deploying to production, they ensured that no unintended changes were introduced into their live environment.

Ultimately, integrating GitLab CI/CD with AWS SAM enabled the HealthTech startup to maintain a secure and efficient deployment process while minimizing potential risks for handling sensitive patient data.

User Story 3: Fintech SaaS Provider

A Fintech SaaS provider wanted to develop and deploy a serverless application with AWS SAM to handle financial transactions and data processing. They required a robust CI/CD pipeline to ensure that their application was reliable, secure and met the high standards demanded by their customers. They opted for GitLab CI/CD to manage their deployment process.

The provider could automate their deployment pipeline by integrating GitLab CI/CD with AWS SAM, ensuring that each stage was executed efficiently and consistently. This included running unit tests, packaging the SAM template, and deploying the application across multiple AWS accounts for development, staging, and production environments.

Dynamic feature branch deployments allowed them to work on multiple features simultaneously without interrupting the primary development branch. They utilized GitLab’s Review Apps feature to thoroughly test new features before merging them into the main branch.

As a result, the Fintech SaaS provider experienced improved collaboration among its development team, faster deployment times, and enhanced security through multi-account AWS deployments.

Benefits of using GitLab CI/CD for AWS SAM deployments

  1. Automation and consistency: GitLab CI/CD automates the process of testing, building, and deploying your AWS SAM applications, ensuring a consistent and repeatable deployment process across different environments.
  2. Faster development and deployment: Automated pipelines reduce the time spent on manual tasks, allowing developers to focus on writing code and delivering new features more quickly.
  3. Improved collaboration: GitLab CI/CD enables better collaboration between team members by providing features such as dynamic feature branch deployments and Review Apps. This help streamlines code reviews and ensures that applications are thoroughly tested before merging changes into the main branch.
  4. Higher quality code: Automated testing in the pipeline helps catch bugs and vulnerabilities earlier in the development process, leading to a more stable and secure application.
  5. Manual approval for production deployments: GitLab CI/CD allows you to enforce manual approval before deploying changes to production, providing an additional layer of safety to prevent unintended changes from reaching your live environment.

Ensuring security in multi-account AWS deployments

  1. Separate environments: Create separate AWS accounts for development, staging, and production environments to maintain security boundaries between resources and access controls.
  2. Cross-account IAM roles: Set up cross-account IAM roles with specific permissions for each environment to restrict access to resources within each account based on the principle of least privilege.
  3. Encryption: Ensure sensitive data is encrypted at rest (e.g., using AWS KMS) and in transit (e.g., using SSL/TLS).
  4. Monitoring and auditing: Enable logging using services like AWS CloudTrail and AWS Config to monitor activity within your accounts, which can help detect unauthorized access or suspicious behavior.

Best practices for integrating GitLab CI/CD with AWS SAM

  1. Single deployment pipeline: Use a single .gitlab-ci.yml file to define your entire pipeline, including testing, building, and deploying stages. This ensures consistency and simplifies the management of your deployment process.
  2. Dynamic feature branch deployments: Leverage dynamic feature branch deployments to work on multiple features simultaneously without interrupting the primary development branch while improving collaboration.
  3. Review Apps: Utilize GitLab’s Review Apps feature to test new features in an isolated environment before merging them into the main branch.
  4. Environment-specific configurations: Use your AWS SAM templates’ environment variables or parameter overrides to manage environment-specific configurations, such as API endpoints or database connections.
  5. Manual approval for production deployments: Configure your pipeline to require manual approval before deploying changes to production, providing an additional safety layer for your live environment.
  6. Rollback strategies: Ensure you have rollback strategies, such as using AWS CloudFormation change sets or stack rollbacks, to quickly revert any unintended changes or issues during deployment.

To learn more about AWS SAM, GitLab CI/CD, and serverless application development, you can explore the following resources:

  1. AWS SAM Documentation: The official AWS Serverless Application Model (SAM) documentation provides detailed guidance on using AWS SAM, creating serverless applications, and working with various AWS services.
  2. GitLab CI/CD Documentation: The official GitLab Continuous Integration and Deployment (CI/CD) documentation offers comprehensive information on setting up GitLab CI/CD pipelines, working with .gitlab-ci.yml files, and managing environments.
  3. Online Courses: Numerous online courses are available for learning AWS SAM or GitLab CI/CD in more depth, such as courses on platforms like Udemy, Coursera, or Pluralsight.
  4. Tutorials and Blogs: Many online tutorials and blogs cover specific use cases or provide step-by-step guides for setting up AWS SAM deployments with GitLab CI/CD. Examples include the AWS Compute Blog and the GitLab Blog.
  5. Community Forums: Engage with fellow developers in community forums such as the AWS Developer Forums or the GitLab Community Forum. These platforms offer a chance to discuss best practices, ask questions, and seek advice from experienced practitioners.
  6. Workshops and Meetups: Attend AWS or GitLab workshops, webinars, and local meetup events to acquire hands-on experience, learn from experts and peers, and network with fellow developers.
  7. Official GitHub Repositories: Explore AWS SAM’s official GitHub repository or GitLab’s example repositories for CI/CD templates to get started with sample projects or learn more about best practices.

By utilizing these resources and continually engaging with the ever-growing serverless development community, you can deepen your knowledge of AWS SAM deployments with GitLab CI/CD and improve your skills in deploying serverless applications.


In these real-world examples, teams successfully leveraged GitLab CI/CD for AWS SAM deployments to enhance their serverless applications’ security, efficiency, and reliability. Companies can maintain strict security boundaries while streamlining their deployment processes by setting up multi-account AWS deployments with separate development, staging, and production environments.

When considering GitLab CI/CD for your AWS SAM deployments, consider best practices such as setting up cross-account IAM roles for authorization and utilizing dynamic feature branch deployments to improve collaboration. By following these strategies and learning from others’ experiences, you can maximize the benefits of using GitLab CI/CD for your serverless applications.

Leave a Comment

Your email address will not be published. Required fields are marked *

Free PDF with a useful Mind Map that illustrates everything you should know about AWS VPC in a single view.