AWS SAM Pipelines generates a starter continuous integration and delivery (CI/CD) configuration for a serverless application. The setup has two separate jobs: sam pipeline bootstrap creates or connects the AWS resources that a deployment stage needs, while sam pipeline init writes a pipeline configuration for your CI/CD provider. Run sam pipeline init --bootstrap for the guided flow that combines them.

The generated pipeline is a starting point. AWS describes the starter as a two-stage deployment, and you must inspect the generated files to confirm what runs before production. Test commands and production approvals need explicit configuration; a job name alone does not mean that tests or an approval gate are active.

AWS documents starter configurations for AWS CodePipeline, Jenkins, GitLab CI/CD, GitHub Actions, and Bitbucket Pipelines. Check the AWS provider list and setup flow for the current options.

Before you start

Prepare a SAM project and tools

Start in the root of an existing AWS SAM project, where its template.yaml and application code live. Install the current AWS SAM CLI using the official installation instructions, and install Git. Docker is needed for local invocation and for builds that use --use-container; it is not a universal prerequisite for every SAM command. See AWS's Docker requirements for SAM.

Before bootstrapping, check the project and CLI from its root:

sam --version
sam validate
sam build

sam validate checks the SAM template, and sam build prepares the application for deployment. If cfn-lint is installed, sam validate --lint adds CloudFormation lint checks. If your build uses containerized dependencies, install and start Docker before adding --use-container. See AWS's sam validate --lint guidance. For an installation walkthrough and local function test, see our AWS SAM local setup guide.

Choose AWS access and permissions

Prepare an AWS CLI credential profile or another approved credential source for every account that will host a deployment stage. In the guided sam pipeline init --bootstrap flow, choose credentials for each stage and verify its account ID and Region in the summary before confirming resource creation. Check a named profile before the guided flow with:

aws sts get-caller-identity --profile sam-testing

AWS's shared profile instructions explain how named profiles are selected. When you run sam pipeline bootstrap separately, pass the intended account's profile and Region with its --profile and --region options for each stage.

The identity running bootstrap needs permission to create or use the resources for each stage. Depending on the permissions method, these include a pipeline IAM user and access key or an OIDC identity provider and roles, a CloudFormation execution role, an S3 artifact bucket, and optionally an Amazon ECR repository for image-based functions. Give this setup work to an authorized administrator or infrastructure role. The identity used by CI/CD should receive only the access it needs to package and deploy the application.

For CI/CD authentication, prefer OpenID Connect (OIDC) when your provider supports it. AWS SAM's OIDC setup supports GitHub Actions, GitLab, and Bitbucket Pipelines. Bootstrap records the provider and repository details in IAM trust so the workflow can assume a role with temporary credentials. Scope that trust to the intended repository and deployment branch, then review the generated trust policy. If you choose IAM access keys instead, store them only in the CI provider's protected secret store, restrict who can read them, and rotate them. The AWS SAM OIDC guide lists the supported providers and setup prompts.

Bootstrap AWS resources and generate the pipeline

Run the guided setup

From the SAM project root, run:

sam pipeline init --bootstrap

Choose an AWS starter template and your CI/CD provider, then follow the prompts for the AWS account, Region, deployment stages, and permissions method. Review the summary before confirming resource creation. The command bootstraps the AWS resources for the stages you configure and generates the provider-specific pipeline file in your repository. Its file format and location depend on the selected provider; there is no universal pipeline/pipeline.yaml plus pipeline/config.yaml pair.

Some teams separate infrastructure provisioning from pipeline setup because the people who can create IAM roles or buckets may differ from application developers. In that case, an administrator runs sam pipeline bootstrap once for each deployment stage in its intended account and Region. The developer then runs sam pipeline init and refers to those existing resources. The sam pipeline bootstrap reference documents its resources and options; the sam pipeline init reference explains the guided --bootstrap option.

Understand the starter stages

AWS's starter pipeline configuration includes two deployment stages. In the current GitHub Actions template, these are named testing and production. Treat them as the template's default path, not a complete development, staging, and production promotion model; extend or replace the template if your release process needs more stages. The starter does not create AWS accounts for you; select the accounts, Regions, and stack names that match your release process. Where possible, keep production in a separate AWS account from testing.

The bootstrap step creates or references the stage's supporting roles and artifact storage. It does not deploy your application stack. The generated CI/CD configuration performs the build, packaging, and deployment steps when its provider triggers the workflow. See AWS's overview of starter CI/CD pipeline generation and supported providers.

Add tests and production controls

Read the generated pipeline file before committing it. In the current AWS GitHub Actions starter, the test and integration-test jobs contain comments where test commands should go. The production job includes a commented example of a GitHub environment; it is not an active approval rule until you configure that environment and its protection rules. Add real test commands and configure any required environment protection before relying on these jobs as a release gate.

The same template deploys matching feature* branches to named stacks in the testing account and deletes those stacks when a branch is deleted. Review these triggers and the testing role's scope before using them. If OIDC trust for the testing role permits only the main branch, those feature-branch jobs cannot assume it; either scope non-production trust to the branches you intend to deploy or disable those jobs. Keep production trust limited to the protected release path. AWS explains how to limit GitHub OIDC role trust by repository and branch.

Other providers have their own templates and controls, so inspect the file for the provider you selected. You can review the AWS GitHub Actions starter workflow in the official template repository.

  • Add the unit and integration test commands your application actually uses, and make failed tests stop the production path.
  • Configure an approval or protected environment in your CI/CD provider if production requires human review.
  • Restrict which branches or protected environments can assume the production role, and verify that the role can deploy only to the intended account and resources.
  • Review IAM policy and trust changes, stack names, Regions, and artifact locations. A successful build does not prove that a deployment is safe.

For guidance on running meaningful checks in CI and verifying deployed AWS workflows, see our guide to end-to-end testing AWS applications.

For more on reviewing generated infrastructure and deployment changes, see our guide to AWS infrastructure-as-code pitfalls.

Verify the first pipeline run

Check the generated files and trigger

Inspect the full diff before committing. Confirm that the trigger branch, AWS account and Region for each stage, stack names, assumed roles, S3 artifact buckets, and any ECR repositories match your plan. Check that test steps run real commands and that the production job depends on passing tests and any required approval. Protect the production branch or environment before a trigger can deploy there.

git status --short
git diff --check
git diff

New files marked ?? in git status --short are not included in git diff; open each generated file at the path shown and review its full contents before committing. If you want an untracked file to appear in a diff, use git add -N <path> for that file, then run git diff -- <path>. Commit the reviewed pipeline configuration and use the provider's run page to follow its first execution. Start with the non-production stage. Confirm that the expected build and tests ran, that the stack deployed in the intended account and Region, and that CloudFormation reports CREATE_COMPLETE on its first deployment or UPDATE_COMPLETE after an update. Inspect the provider log and CloudFormation stack events if a stage fails. Do not treat an empty placeholder test job as evidence that the application was tested.

Keep development and production paths separate

For rapid cloud testing during development, sam sync --watch can sync local changes to a development stack. AWS recommends sam sync for development; use sam deploy or the CI/CD pipeline for production deployments. A sync can update resources directly through service APIs and create CloudFormation drift, so do not point a watch session at production. See AWS's sam sync guidance.

Troubleshoot common failures

IAM or OIDC access is denied

Run aws sts get-caller-identity with the profile used for bootstrap to verify the account. For a CI failure, confirm the workflow's OIDC provider, repository and branch conditions, and role ARN agree with the bootstrap configuration. If using IAM keys, check that the CI provider is reading the intended protected secrets. Then identify the denied AWS action in the CI log or CloudTrail event and add only the missing permission to the responsible role.

The build or test stage fails

Check the provider's build log for a missing runtime, dependency, or container requirement. Run sam validate and sam build locally with the same template and build options. If the workflow shows a test job as successful but no tests ran, add the test command and verify that a deliberate failing test causes the job to fail.

The CloudFormation deployment fails

Check the stack events in the same account and Region as the failed stage. Confirm the CloudFormation execution role can create or update the resources in the SAM template and the pipeline role can pass that role. The current GitHub starter passes CAPABILITY_IAM; if your template gives IAM resources custom names, sam deploy requires CAPABILITY_NAMED_IAM. Check the sam deploy capability requirements along with the artifact bucket or ECR repository for the target Region and package type.

The starter deploy command does not pass --disable-rollback; SAM defaults to rolling back a failed deployment unless the project configuration disables it. A rollback can also fail, so check the final stack status and events. If an update reaches UPDATE_ROLLBACK_FAILED, fix the cause and continue the rollback before trying another deployment. See AWS's guidance for continuing a failed CloudFormation rollback. Review IAM changes and resource replacements before retrying, then rerun the same reviewed pipeline path.