> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/3.0/use-deployments/aws-sam/sam-deploy.md).

# 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 <a href="#what-you-will-learn" id="what-you-will-learn"></a>

* 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 <a href="#settings" id="settings"></a>

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`.                                               |

{% hint style="info" %}
**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.
{% endhint %}

***

### YAML reference <a href="#yaml-reference" id="yaml-reference"></a>

```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 <a href="#rollback-behavior" id="rollback-behavior"></a>

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 <a href="#next-steps" id="next-steps"></a>

* Go to [SAM Build](/continuous-delivery/3.0/use-deployments/aws-sam/sam-build.md) for the build step reference.
* Go to [AWS SAM overview](/continuous-delivery/3.0/use-deployments/aws-sam/overview.md) for the full stage setup and runtime configuration.
* Go to [SAM infrastructure](/continuous-delivery/3.0/use-deployments/aws-sam/sam-infrastructure.md) for connector and region configuration.

{% @harness-feedback/feedback %}