Deployment scripts allow you to execute custom logic as part of your deployment process. You can pass information about your infrastructure to the script and grant it permissions to interact with other resources in your stack.
Under the hood, a deployment script is packaged as an AWS Lambda function and triggered during the deployment or delete process. Deployment scripts are not executed during hot-swap deployments.
When to use them
Deployment scripts are useful for tasks that need to run as part of your infrastructure provisioning, such as:
- Seeding a database with initial data.
- Running database migrations.
- Running smoke tests to ensure that your application is running correctly after a deployment.
Basic usage
This example uses a deployment script to test a public API endpoint after a deployment.
DeploymentScriptAPI referencetypeRequired
Type: string "deployment-script"
properties.triggerRequired
When to run: after:deploy (fails → rollback) or before:delete (fails → deletion continues).
Type: string ENUM
Possible values: after:deploybefore:delete
properties.packagingRequired
How the script code is packaged. Use stacktape-lambda-buildpack for auto-bundling.
Type: LambdaPackaging
properties.runtime
Lambda runtime. Auto-detected from file extension if not specified.
Type: string ENUM
Possible values: dotnet6dotnet7dotnet8java11java17java8java8.al2nodejs18.xnodejs20.xnodejs22.xnodejs24.xprovided.al2provided.al2023python3.10python3.11python3.12python3.13python3.8python3.9ruby3.3
properties.environment
Environment variables injected at runtime. Use $ResourceParam() or $Secret() for dynamic values.
Type: Array of EnvironmentVar
properties.parameters
Structured data passed to the handler function as the event payload. Not for secrets — use environment.
Type: Object
properties.memory
Memory in MB (128–10,240). CPU scales proportionally — 1,769 MB = 1 vCPU.
Type: number
properties.timeoutDefault: 10
Max execution time in seconds. Max: 900 (15 minutes).
Type: number
properties.joinDefaultVpc
Connect to VPC resources (databases, Redis). Warning: function loses direct internet access.
Type: boolean
properties.storageDefault: 512
Ephemeral /tmp storage in MB (512–10,240).
Type: number
properties.connectTo
Give this resource access to other resources in your stack.
Type: Array of string
List the names of resources this workload needs to communicate with. Stacktape automatically:
- Grants IAM permissions (e.g., S3 read/write, SQS send/receive)
- Opens network access (security group rules for databases, Redis)
- Injects environment variables with connection details:
STP_[RESOURCE_NAME]_[PARAM]
Example: connectTo: ["myDatabase", "myBucket"] gives this workload full access to both
resources and injects STP_MY_DATABASE_CONNECTION_STRING, STP_MY_BUCKET_NAME, etc.
properties.iamRoleStatements
Raw IAM policy statements for permissions not covered by connectTo.
Type: Array of StpIamRoleStatement
Added as a separate policy alongside auto-generated permissions. Use this for accessing AWS services directly (e.g., Rekognition, Textract, Bedrock).
overrides
Escape hatch to modify the underlying CloudFormation resources Stacktape creates.
Type: Object
Use dot-notation paths to override specific properties on any child resource.
Find resource logical IDs with stacktape stack-info --detailed.
overrides:
MyDbInstance:
Properties.StorageEncrypted: true
A deployment script in TypeScript (
test-url.ts).
The Stacktape configuration for the deployment script.
Trigger
The trigger property determines when the script is executed.
When to run: after:deploy (fails → rollback) or before:delete (fails → deletion continues).
Scripts that are triggered before a stack is deleted before:delete must have been present during the last deployment to be executed.
Packaging
Deployment scripts are packaged and executed as Lambda functions. For more information, see the documentation on packaging Lambda functions.
Parameters
You can pass parameters to your deployment script.
Structured data passed to the handler function as the event payload. Not for secrets — use environment.
Environment variables
Environment variables injected at runtime. Use $ResourceParam() or $Secret() for dynamic values.
EnvironmentVarAPI referenceParent:DeploymentScriptnameRequired
Environment variable name (e.g., DATABASE_URL, API_KEY).
Type: string
valueRequired
Environment variable value. Numbers and booleans are converted to strings.
Type: string or number or boolean
Accessing other resources
By default, AWS resources cannot communicate with each other. Access must be granted using IAM permissions.
Stacktape automatically handles the necessary permissions for the services it manages. For example, it allows a deployment script to write logs to CloudWatch.
However, if your script needs to access other resources, you must grant permissions manually. You can do this in two ways:
Using connectTo
The connectTo property lets you grant access to other Stacktape-managed resources by simply listing their names. Stacktape automatically configures the required IAM permissions and injects connection details as environment variables into your script.
List the names of resources this workload needs to communicate with. Stacktape automatically:
- Grants IAM permissions (e.g., S3 read/write, SQS send/receive)
- Opens network access (security group rules for databases, Redis)
- Injects environment variables with connection details:
STP_[RESOURCE_NAME]_[PARAM]
Example: connectTo: ["myDatabase", "myBucket"] gives this workload full access to both
resources and injects STP_MY_DATABASE_CONNECTION_STRING, STP_MY_BUCKET_NAME, etc.
Using iamRoleStatements
For more granular control, you can provide a list of raw IAM role statements. These statements are added to the script's IAM role, allowing you to define precise permissions for any AWS resource.
API reference
StpIamRoleStatementAPI referenceParent:DeploymentScriptResourceRequired
ARNs of the AWS resources this statement applies to. Use "*" for all resources.
Type: Array of string
Sid
Optional identifier for this statement (for readability).
Type: string
EffectDefault: Allow
Whether to allow or deny the specified actions.
Type: string
Action
AWS actions to allow or deny (e.g., s3:GetObject, sqs:SendMessage).
Type: Array of string
Condition
Type: UNSPECIFIED