SAM Build

Reference for the AWS SAM Build step — builds an AWS SAM application inside a Lambda-compatible container using sam build.

What you will learn

• What fields are available on the SAM Build step, which are required, and which are optional overrides.

• How to configure the --use-container flag and Docker registry credentials for container-based builds.

---

The SAM Build step runs sam build against the downloaded SAM directory manifest. When --use-container is set in the command options, the build runs inside a Lambda-compatible Docker container provided by the DinD background step. The step outputs the packaged application to .aws-sam/build/ for the SAM Deploy step to use.

---

Settings

The following fields are available in the SAM Build step.

Field	Required	Description
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 build. Include --use-container to build Lambda packages inside a Lambda-compatible container.
Pre-Execute Command	Optional	Shell command to run before sam build, for example npm install. Useful for installing dependencies the build requires.
Working Directory	Optional	Working directory for the build. 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 for the build, for example us-east-1. Derived from the infrastructure definition.
Docker Retry Count	Optional	Number of times Harness polls for a running Docker daemon before starting. Default: 3. Requires the DinD background step.
Docker Registry URL	Optional	URL of the registry for the Lambda runtime build container, for example https://index.docker.io/v2/. Required when --use-container is set.
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 Build step. Defaults to harnessdev/aws-sam-dev:0.0.12.

--USE-CONTAINER REQUIREMENT

Include --use-container in SAM Build Command Options to build Lambda packages inside a container that matches the Lambda execution environment. Without this flag, SAM builds on the host directly and may produce packages incompatible with the Lambda runtime.

---

Step YAML

- name: AWS SAM Build
  id: awsSamBuildStep
  template:
    uses: awsSamBuildStep
    with:
      connector: <aws-connector>
      region: <aws-region>
      stack: <cloudformation-stack-name>
      cmd_opts: --use-container
      docker_retry_count: '3'
      registry_url: https://index.docker.io/v2/
      registry_username: <registry-username>
      registry_pwd: <registry-password-secret>

---

Next steps

• Go to SAM Deploy for the deploy step reference.

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

• Go to SAM services for manifest and values.yaml configuration.