SAM Deploy

Reference for the AWS SAM Deploy step — packages and deploys an AWS SAM application to a CloudFormation stack using sam deploy.

What you will learn

• What fields are available on the SAM Deploy step, including the required Stack field and common deploy flags.

• How CloudFormation handles stack rollback automatically when a deployment fails.

---

The SAM Deploy step runs sam deploy to package the SAM Build output to S3 and create or update the target CloudFormation stack. The step waits for the stack to reach a stable state and prints CloudFormation events and stack outputs to the step log.

---

Settings

The following fields are available in the SAM Deploy step.

Field	Required	Description
Stack	Yes	The CloudFormation stack name to create or update.
Template File Path	Optional	Path to the SAM template file relative to the SAM directory root, for example template.yaml. Defaults to template.yaml.
Command Options	Optional	Flags passed to sam deploy, for example --capabilities CAPABILITY_IAM --resolve-s3 --no-fail-on-empty-changeset.
Pre-Execute Command	Optional	Shell command to run before sam deploy, for example npm install.
Working Directory	Optional	Working directory for the deploy. Derived from the service configuration.
AWS Connector	Yes	A Harness AWS connector with CloudFormation and S3 permissions. Derived from the infrastructure definition.
Region	Yes	The AWS region to deploy to. Derived from the infrastructure definition and passed as --region to sam deploy automatically.
Docker Registry URL	Optional	URL of the container registry, for example https://index.docker.io/v2/.
Docker Registry Username	Optional	Username for the container registry.
Docker Registry Password	Optional	Secret reference for the container registry password.
Command Timeout	Optional	Maximum time the step can run before Harness marks it failed, for example 10m.
Log Level	Optional	Logging verbosity for the step. Default: info.
Container Registry	Optional	Harness connector for the registry that hosts the SAM plugin container image. Leave empty to use the default image from Docker Hub.
Image	Optional	Container image for the SAM Deploy step. Defaults to harnessdev/aws-sam-dev:0.0.12.

COMMON DEPLOY FLAGS

--capabilities CAPABILITY_IAM is required when your SAM template creates IAM roles or policies. --resolve-s3 tells SAM to automatically create an S3 bucket for deployment artifacts. --no-fail-on-empty-changeset prevents the step from failing when there are no changes to deploy.

---

Step YAML

- name: AWS SAM Deploy
  id: awsSamDeployStep
  template:
    uses: awsSamDeployStep
    with:
      connector: <aws-connector>
      region: <aws-region>
      stack: <cloudformation-stack-name>
      cmd_opts: --capabilities CAPABILITY_IAM --resolve-s3 --no-fail-on-empty-changeset
      registry_url: https://index.docker.io/v2/
      registry_username: <registry-username>
      registry_pwd: <registry-password-secret>

---

Rollback behavior

CloudFormation handles rollback implicitly. If the SAM Deploy step fails mid-update, CloudFormation automatically rolls the stack back to its last stable state. On a first deployment failure where no previous stack state exists, CloudFormation deletes the partially created stack. Harness does not issue a separate rollback command.

---

Next steps

• Go to SAM Build for the build step reference.

• Go to AWS SAM overview for the full stage setup and runtime configuration.

• Go to SAM infrastructure for connector and region configuration.