Multi-Account AWS SAM Deployments with GitLab CI/CD

Introduction

AWS SAM (Serverless Application Model) lets you define and deploy serverless applications using CloudFormation templates. If you’re using GitLab CI/CD, you can automate the entire build and deployment workflow across multiple AWS accounts.

This guide covers setting up multi-account AWS SAM deployments with GitLab CI/CD. You’ll learn how to configure cross-account IAM roles and how to structure your pipeline for testing, building, and deploying serverless applications.

Multi-Account AWS Deployments

Separate AWS accounts for development, staging, and production is standard practice. It prevents a misconfigured Lambda in staging from accidentally touching production resources.

Setting Up Cross-Account IAM Roles

1. Create AWS accounts for each environment (dev, staging, production).
2. Create IAM roles in each account that grant GitLab access to the services you need: Lambda, API Gateway, DynamoDB, and S3.
3. Create an S3 bucket in your shared services account to store deployment artifacts.
4. Configure the AssumeRole in your pipeline so GitLab can access each account securely.

Pipeline Structure

Your .gitlab-ci.yml file defines the pipeline. A typical setup has three stages: test, build, and deploy.

Testing Stage

Run unit tests and security scans against your code. Catch problems before they reach any environment.

Build Stage

Package your SAM template and code using the aws cloudformation package command. This uploads Lambda code to S3 and outputs a new template with references to those artifacts.

Deploy Stage

Use CloudFormation to deploy the packaged template to your target environment. For production, add a manual approval gate so someone explicitly triggers the deployment.

Example

Here’s a .gitlab-ci.yml that builds and deploys an AWS SAM application:

image: node:20

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

stages:
  - test
  - build
  - deploy

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

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

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

deploy_development:
  <<: *deploy_definition
  environment:
    name: development
  only:
    refs:
      - develop

deploy_staging:
  <<: *deploy_definition
  environment:
    name: staging
    url: https://staging.example.com
  when: manual
  only:
    refs:
      - staging

deploy_production:
  <<: *deploy_definition
  environment:
    name: production
    url: https://www.example.com
  when: manual
  only:
    refs:
      - main

This pipeline runs tests, builds the SAM application, and deploys to three environments. Staging and production require manual approval before deploying.

Dynamic Feature Branch Deployments and Review Apps

Feature branches let developers work in parallel without touching the main codebase. GitLab CI/CD supports this with Review Apps, which let you preview an application instance during code review.

To set this up, define an environment in your deployment job. GitLab automatically tracks deployed environments and links them to their branches.

Use the on_stop property to define a job that tears down the environment when the branch is deleted. This stops unused resources from running up your bill.

Integration Steps

Here’s how to connect GitLab CI/CD with AWS SAM:

1. Create a GitLab project to host your SAM application and pipeline configuration.
2. Add AWS credentials as environment variables in your GitLab project settings.
3. Define your pipeline in .gitlab-ci.yml at the project root.
4. Push changes to trigger the pipeline and watch the stages complete in the GitLab interface.
5. Use Review Apps to see your application running during code review.

User Stories

E-commerce Platform

A retail company built a scalable serverless backend with AWS SAM to handle their growing order volume. They used GitLab CI/CD to manage deployments across dev, staging, and production accounts.

Dynamic feature branch deployments let their team ship features faster. Review Apps caught bugs before they reached production. When something went wrong, they rolled back using CloudFormation stack policies.

HealthTech Startup

A healthcare company processed patient data through a serverless application. The nature of the data required strict security boundaries and multi-account isolation.

Cross-account IAM roles limited access so each environment could only reach its own resources. Manual approval gates for production ensured that no deployment happened without review. This gave them an audit trail for compliance.

Fintech SaaS Provider

A fintech company deployed a transaction processing system with AWS SAM. They needed a reliable pipeline that met high security standards.

GitLab CI/CD ran their tests, packaged their SAM templates, and deployed across accounts automatically. Feature branches allowed multiple teams to work on different features simultaneously. Review Apps let them validate each change before merging.

Benefits of GitLab CI/CD with AWS SAM

1. Automation: The pipeline handles testing, building, and deploying without manual steps.
2. Consistency: Every deployment follows the same process.
3. Speed: Developers push code and the pipeline handles the rest.
4. Collaboration: Review Apps and branch deployments make code reviews more effective.
5. Safety: Manual approval gates for production prevent accidental deployments.

Security in Multi-Account Deployments

1. Separate accounts: Keep dev, staging, and production in different AWS accounts.
2. Cross-account IAM roles: Use roles with least-privilege permissions for each environment.
3. Encryption: Enable encryption at rest with KMS and in transit with TLS.
4. Monitoring: Use CloudTrail and AWS Config to log activity and detect unauthorized access.

Best Practices

1. Single pipeline file: Define all stages in one .gitlab-ci.yml for consistency.
2. Feature branch deployments: Test changes in isolated environments before merging.
3. Review Apps: Catch issues early by previewing applications during review.
4. Environment-specific config: Use SAM template parameters or environment variables for each environment.
5. Manual approvals: Require human sign-off for production deployments.
6. Rollback plans: Know how to revert using CloudFormation change sets or stack rollbacks.

Resources

1. AWS SAM Documentation
2. GitLab CI/CD Documentation
3. AWS Compute Blog
4. GitLab Blog
5. AWS Developer Forums
6. GitLab Community Forum
7. AWS SAM GitHub Repository
8. GitLab CI/CD Templates

Conclusion

Multi-account AWS deployments with separate dev, staging, and production environments give you security boundaries and isolation. GitLab CI/CD automates the entire process from test to deployment, while manual approval gates add a safety layer for production.

Setting up cross-account IAM roles and dynamic feature branch deployments lets your team iterate quickly without sacrificing safety. The examples above show how different companies handle real-world serverless deployment challenges.