Deployment Scripts



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 reference
typeRequired
No description

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
import fetch from 'node-fetch';

export default async (event) => {
  const { apiURL } = event;

  // do whatever you want with apiURL ...
  const result = await fetch(apiURL);

  // fail the script if the test fails
  if (result.statusCode === 404) {
    throw Error('API test failed');
  }
};

A deployment script in TypeScript (test-url.ts).

resources:
  myHttpApi:
    type: http-api-gateway

  testApiMethods:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      parameters:
        apiURL: $ResourceParam('myHttpApi', 'url')

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

resources:
  myHttpApi:
    type: http-api-gateway

  testApiMethods:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      parameters:
        apiURL: $ResourceParam('myHttpApi', 'url')

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.

resources:
  myHttpApi:
    type: http-api-gateway

  testApiMethods:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      parameters:
        apiURL: $ResourceParam('myHttpApi', 'url')
        testPaths:
          - my/path/1
          - my/path/2

Environment variables

Environment variables injected at runtime. Use $ResourceParam() or $Secret() for dynamic values.

EnvironmentVarAPI referenceParent:DeploymentScript
nameRequired

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

resources:
  myDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: $Secret('my-database-password')
      engine:
        type: aurora-postgresql-serverless

  testDatabase:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: test-url.ts
      environment:
        - name: DATABASE_URL
          value: $ResourceParam('myDatabase', 'connectionString')

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.

resources:
  myScript:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my-script.ts
      environment:
        - name: MY_BUCKET_NAME
          value: $ResourceParam('myBucket', 'name')
      connectTo:
        # access to the bucket
        - myBucket
        # access to AWS SES
        - aws:ses

  myBucket:
    type: bucket

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.

resources:
  myScript:
    type: deployment-script
    properties:
      trigger: after:deploy
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my-script.ts
      environment:
        - name: TOPIC_ARN
          value: $CfResourceParam('NotificationTopic', 'Arn')
      iamRoleStatements:
        - Resource:
            - $CfResourceParam('NotificationTopic', 'Arn')
          Effect: 'Allow'
          Action:
            - 'sns:Publish'

cloudformationResources:
  NotificationTopic:
    Type: AWS::SNS::Topic

API reference

StpIamRoleStatementAPI referenceParent:DeploymentScript
ResourceRequired

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
No description

Type: UNSPECIFIED