Scripts



Scripts allow you to define custom commands that can be executed as part of your workflow. They can be used to perform a variety of tasks, such as building your application, running database migrations, or sending notifications.

Use connectTo in a script to auto-inject database URLs, API keys, etc. as environment variables. Run scripts with stacktape script:run --scriptName myScript or attach them to hooks.

Script types:

  • local-script: Runs on your machine (or CI). Good for migrations, builds, seed scripts.
  • local-script-with-bastion-tunneling: Runs locally but tunnels connections to VPC-only resources (e.g., private databases) through a bastion host.
  • bastion-script: Runs remotely on the bastion host inside your VPC.

Scripts can be shell commands or JS/TS/Python files.

scripts:
  buildWeb:
    type: local-script
    properties:
      executeCommand: npx gatsby build

hooks:
  beforeDeploy:
    - scriptName: buildWeb

Local script

A local script is executed on the same machine where the Stacktape command is run.

  • The script must define one of the following properties: executeCommand, executeScript, executeCommands, or executeScripts.
  • You can use the connectTo property to list the resources that your script needs to access. Stacktape will automatically inject the necessary environment variables for connecting to those resources. For more information, see Connecting to resources.

executeCommand

A single terminal command to execute in a separate shell process.

The command runs on the machine executing the Stacktape command. Be aware of potential differences between local and CI environments (e.g., OS, shell). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

scripts:
  buildWeb:
    type: local-script
    properties:
      executeCommand: npx gatsby build

executeScript

The path to a script file to execute. The script can be written in JavaScript, TypeScript, or Python and runs in a separate process.

The executable is determined by defaults:configure or the system default (node for JS/TS, python for Python). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

scripts:
  sendSlackNotification:
    type: local-script
    properties:
      executeScript: scripts/send-slack-notification.ts
import { WebClient } from "@slack/web-api";

const token = "my-access-token";
const conversationId = "my-conversation-id";
const slackClient = new WebClient(token);
const errorData = JSON.parse(process.env.STP_ERROR);

(async () => {
  await slackClient.chat.postMessage({
    channel: conversationId,
    text: errorData.message
  });
})();

executeCommands

A list of terminal commands to execute sequentially. Each command runs in a separate shell process.

The commands run on the machine executing the Stacktape command. Be aware of potential differences between environments. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

scripts:
  buildWeb:
    type: local-script
    properties:
      executeCommands:
        - poetry run python manage.py makemigrations
        - poetry run python manage.py migrate

executeScripts

A list of script files to execute sequentially. Each script runs in a separate process.

The script can be written in JavaScript, TypeScript, or Python. The executable is determined by defaults:configure or the system default. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

scripts:
  sendSlackNotification:
    type: local-script
    properties:
      executeScripts:
        - scripts/run-migration.ts
        - scripts/send-slack-notification.ts

Local script with bastion tunneling

A local script with bastion tunneling is executed in the same way as a regular local script, but connections to the resources listed in the connectTo property are tunneled through a bastion server.

  • This provides a secure, encrypted connection to your resources.
  • It allows you to connect to resources that do not have a public endpoint and are only accessible within the stack's default VPC, such as a private relational-database or redis-cluster.
  • The environment variables injected by the connectTo property are automatically adjusted to use the tunneled endpoints.

Your stack must have a bastion resource to use this type of script.

scripts:
  migrateDb:
    type: local-script-with-bastion-tunneling
    properties:
      executeScript: migrate.ts
      connectTo:
        - myDatabase

hooks:
  afterDeploy:
    - scriptName: migrateDb

resources:
  myBastion:
    type: bastion

  myDatabase:
    type: relational-database
    properties:
      # database is only accessible from withing VPC
      accessibility:
        accessibilityMode: vpc
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro
      credentials:
        masterUserPassword: my_secret_pass
import { DbClient } from './db';

// using environment variable which was automatically injected thanks to connectTo property
// injected environment variables are using tunneled endpoint
const databaseConnectionString = process.env.STP_MY_DATABASE_CONNECTION_STRING;

const client = new DbClient({ connectionString: databaseConnectionString });

// perform migrations with the client

client.close();

Graphical overview of tunneling

Bastion tunneling is supported for the following resource types:

  • relational-database
  • redis-cluster
  • application-load-balancer
  • private-service (with loadBalancing.type set to application-load-balancer)

Bastion script

A bastion script is executed remotely on a bastion server.

  • Logs from the script's execution are streamed in real-time to your local machine.
  • This provides a unified way to execute a set of commands from anywhere.
  • You can use the connectTo property to list the resources that your script needs to access. Stacktape will automatically inject the necessary environment variables for connecting to those resources. For more information, see Connecting to resources.
scripts:
  dbScript:
    type: bastion-script
    properties:
      executeCommands:
        - psql $STP_MY_DATABASE_CONNECTION_STRING -c "SELECT 1 where 1=1"
      connectTo:
        - myDatabase

hooks:
  afterDeploy:
    - scriptName: dbScript

resources:
  myBastion:
    type: bastion
    properties:
      runCommandsAtLaunch:
        - yum update
        - yum install postgresql.x86_64 -y

  myDatabase:
    type: relational-database
    properties:
      accessibility:
        accessibilityMode: vpc
      engine:
        type: postgres
        properties:
          version: '16.2'
          primaryInstance:
            instanceSize: db.t3.micro
      credentials:
        masterUserPassword: my_secret_pass

Connecting to resources

A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.

Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).

Injected Variables by Resource Type:

  • Bucket: NAME, ARN
  • DynamoDbTable: NAME, ARN, STREAM_ARN
  • MongoDbAtlasCluster: CONNECTION_STRING
  • RelationalDatabase: CONNECTION_STRING, JDBC_CONNECTION_STRING, HOST, PORT. For Aurora clusters, READER_CONNECTION_STRING, READER_JDBC_CONNECTION_STRING, and READER_HOST are also included.
  • RedisCluster: HOST, READER_HOST, PORT
  • EventBus: ARN
  • Function: ARN
  • BatchJob: JOB_DEFINITION_ARN, STATE_MACHINE_ARN
  • UserAuthPool: ID, CLIENT_ID, ARN
  • SnsTopic: ARN, NAME
  • SqsQueue: ARN, NAME, URL
  • UpstashKafkaTopic: TOPIC_NAME, TOPIC_ID, USERNAME, PASSWORD, TCP_ENDPOINT, REST_URL
  • UpstashRedis: HOST, PORT, PASSWORD, REST_TOKEN, REST_URL, REDIS_URL
  • PrivateService: ADDRESS
  • WebService: URL
scripts:
  dbScript:
    type: local-script
    properties:
      # The $STP_MY_DATABASE_CONNECTION_STRING environment variable is injected by connectTo
      executeCommands:
        - psql $STP_MY_DATABASE_CONNECTION_STRING -c "SELECT * FROM users"
      connectTo:
        - myDatabase

resources:
  myDatabase:
    type: relational-database
    properties:
      engine:
        type: postgres
        properties:
          primaryInstance:
            instanceSize: db.t3.micro

If you are using a local-script-with-bastion-tunneling script, connections to the resources listed in the connectTo property are tunneled through a bastion host. This allows you to access resources that are only accessible from within the VPC and increases the security of the connection. For more information, see Local script with bastion tunneling.

How to execute a script

A script can be executed in two ways:

  • Using the script:run command:

    stacktape script:run --scriptName <<scriptName>> --stage <<stage>>
  • Inside a hook.

Environment variables

A list of environment variables to pass to the script or command.

Values can be:

scripts:
  migrateDb:
    executeScript: scripts/migrate-db.ts
    environment:
      - name: DB_CONNECTION_STRING
        value: $ResourceParam('mainDatabase', 'connectionString')

resources:
  mainDatabase:
    type: relational-database
    properties:
      credentials:
        masterUserPassword: my_secret_password
      engine:
        type: mysql
        properties:
          primaryInstance:
            instanceSize: db.t2.micro

Permissions

You can use the assumeRoleOfResource property to grant a script the same AWS permissions as a specific resource.

The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.

The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.

Supported Resource Types:

  • function
  • batch-job
  • worker-service
  • web-service
  • private-service
  • multi-container-workload
  • nextjs-web
  • astro-web
  • nuxt-web
  • sveltekit-web
  • solidstart-web
  • tanstack-web
  • remix-web
scripts:
  seedDb:
    executeScript: scripts/seed-db.ts
    assumeRoleOfResource: myFunction
    environment:
      - name: TABLE_NAME
        value: $ResourceParam('dynamoTable', 'name')

resources:
  dynamoTable:
    type: dynamo-db-table

  myFunction:
    type: function
    properties:
      allowAccessTo:
        - dynamoTable

API reference

LocalScriptAPI reference
typeRequired
No description

Type: string "local-script"

properties.executeScript

Execute Script

Type: string

The path to a script file to execute. The script can be written in JavaScript, TypeScript, or Python and runs in a separate process.

The executable is determined by defaults:configure or the system default (node for JS/TS, python for Python). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.executeCommand

Execute Command

Type: string

A single terminal command to execute in a separate shell process.

The command runs on the machine executing the Stacktape command. Be aware of potential differences between local and CI environments (e.g., OS, shell). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.executeScripts

Execute Scripts

Type: Array of string

A list of script files to execute sequentially. Each script runs in a separate process.

The script can be written in JavaScript, TypeScript, or Python. The executable is determined by defaults:configure or the system default. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.executeCommands

Execute Commands

Type: Array of string

A list of terminal commands to execute sequentially. Each command runs in a separate shell process.

The commands run on the machine executing the Stacktape command. Be aware of potential differences between environments. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.cwdDefault: The directory where the Stacktape command was executed.

Working Directory

Type: string

The directory where the script or command will be executed.

properties.pipeStdioDefault: true

Pipe Stdio

Type: boolean

If true, pipes the standard input/output (stdio) of the hook process to the main process. This allows you to see logs from your hook and interact with prompts.

properties.connectTo

Connect To

Type: Array of string

A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.

Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).

Injected Variables by Resource Type:

  • Bucket: NAME, ARN
  • DynamoDbTable: NAME, ARN, STREAM_ARN
  • MongoDbAtlasCluster: CONNECTION_STRING
  • RelationalDatabase: CONNECTION_STRING, JDBC_CONNECTION_STRING, HOST, PORT. For Aurora clusters, READER_CONNECTION_STRING, READER_JDBC_CONNECTION_STRING, and READER_HOST are also included.
  • RedisCluster: HOST, READER_HOST, PORT
  • EventBus: ARN
  • Function: ARN
  • BatchJob: JOB_DEFINITION_ARN, STATE_MACHINE_ARN
  • UserAuthPool: ID, CLIENT_ID, ARN
  • SnsTopic: ARN, NAME
  • SqsQueue: ARN, NAME, URL
  • UpstashKafkaTopic: TOPIC_NAME, TOPIC_ID, USERNAME, PASSWORD, TCP_ENDPOINT, REST_URL
  • UpstashRedis: HOST, PORT, PASSWORD, REST_TOKEN, REST_URL, REDIS_URL
  • PrivateService: ADDRESS
  • WebService: URL
properties.environment

Environment Variables

Type: Array of EnvironmentVar

A list of environment variables to pass to the script or command.

Values can be:

properties.assumeRoleOfResource

Assume Role of Resource

Type: string

The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.

The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.

Supported Resource Types:

  • function
  • batch-job
  • worker-service
  • web-service
  • private-service
  • multi-container-workload
  • nextjs-web
  • astro-web
  • nuxt-web
  • sveltekit-web
  • solidstart-web
  • tanstack-web
  • remix-web
LocalScriptWithBastionTunnelingAPI reference
typeRequired
No description

Type: string "local-script-with-bastion-tunneling"

properties.bastionResource

Bastion Resource Name

Type: string

The name of the bastion resource to use for tunneling to protected resources.

properties.executeScript

Execute Script

Type: string

The path to a script file to execute. The script can be written in JavaScript, TypeScript, or Python and runs in a separate process.

The executable is determined by defaults:configure or the system default (node for JS/TS, python for Python). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.executeCommand

Execute Command

Type: string

A single terminal command to execute in a separate shell process.

The command runs on the machine executing the Stacktape command. Be aware of potential differences between local and CI environments (e.g., OS, shell). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.executeScripts

Execute Scripts

Type: Array of string

A list of script files to execute sequentially. Each script runs in a separate process.

The script can be written in JavaScript, TypeScript, or Python. The executable is determined by defaults:configure or the system default. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.executeCommands

Execute Commands

Type: Array of string

A list of terminal commands to execute sequentially. Each command runs in a separate shell process.

The commands run on the machine executing the Stacktape command. Be aware of potential differences between environments. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.

properties.cwdDefault: The directory where the Stacktape command was executed.

Working Directory

Type: string

The directory where the script or command will be executed.

properties.pipeStdioDefault: true

Pipe Stdio

Type: boolean

If true, pipes the standard input/output (stdio) of the hook process to the main process. This allows you to see logs from your hook and interact with prompts.

properties.connectTo

Connect To

Type: Array of string

A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.

Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).

Injected Variables by Resource Type:

  • Bucket: NAME, ARN
  • DynamoDbTable: NAME, ARN, STREAM_ARN
  • MongoDbAtlasCluster: CONNECTION_STRING
  • RelationalDatabase: CONNECTION_STRING, JDBC_CONNECTION_STRING, HOST, PORT. For Aurora clusters, READER_CONNECTION_STRING, READER_JDBC_CONNECTION_STRING, and READER_HOST are also included.
  • RedisCluster: HOST, READER_HOST, PORT
  • EventBus: ARN
  • Function: ARN
  • BatchJob: JOB_DEFINITION_ARN, STATE_MACHINE_ARN
  • UserAuthPool: ID, CLIENT_ID, ARN
  • SnsTopic: ARN, NAME
  • SqsQueue: ARN, NAME, URL
  • UpstashKafkaTopic: TOPIC_NAME, TOPIC_ID, USERNAME, PASSWORD, TCP_ENDPOINT, REST_URL
  • UpstashRedis: HOST, PORT, PASSWORD, REST_TOKEN, REST_URL, REDIS_URL
  • PrivateService: ADDRESS
  • WebService: URL
properties.environment

Environment Variables

Type: Array of EnvironmentVar

A list of environment variables to pass to the script or command.

Values can be:

properties.assumeRoleOfResource

Assume Role of Resource

Type: string

The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.

The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.

Supported Resource Types:

  • function
  • batch-job
  • worker-service
  • web-service
  • private-service
  • multi-container-workload
  • nextjs-web
  • astro-web
  • nuxt-web
  • sveltekit-web
  • solidstart-web
  • tanstack-web
  • remix-web
BastionScriptAPI reference
typeRequired
No description

Type: string "bastion-script"

properties.bastionResource

Bastion Resource Name

Type: string

The name of the bastion resource on which the commands will be executed.

properties.executeCommand

Execute Command

Type: string

A single terminal command to execute on the bastion host. Logs from the execution are streamed to your terminal.

You can use either executeCommand or executeCommands, but not both.

properties.executeCommands

Execute Commands

Type: Array of string

A list of terminal commands to execute sequentially as a script on the bastion host. Logs from the execution are streamed to your terminal.

You can use either executeCommand or executeCommands, but not both.

properties.cwdDefault: /

Working Directory

Type: string

The directory on the bastion host where the command will be executed.

properties.connectTo

Connect To

Type: Array of string

A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.

Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).

Injected Variables by Resource Type:

  • Bucket: NAME, ARN
  • DynamoDbTable: NAME, ARN, STREAM_ARN
  • MongoDbAtlasCluster: CONNECTION_STRING
  • RelationalDatabase: CONNECTION_STRING, JDBC_CONNECTION_STRING, HOST, PORT. For Aurora clusters, READER_CONNECTION_STRING, READER_JDBC_CONNECTION_STRING, and READER_HOST are also included.
  • RedisCluster: HOST, READER_HOST, PORT
  • EventBus: ARN
  • Function: ARN
  • BatchJob: JOB_DEFINITION_ARN, STATE_MACHINE_ARN
  • UserAuthPool: ID, CLIENT_ID, ARN
  • SnsTopic: ARN, NAME
  • SqsQueue: ARN, NAME, URL
  • UpstashKafkaTopic: TOPIC_NAME, TOPIC_ID, USERNAME, PASSWORD, TCP_ENDPOINT, REST_URL
  • UpstashRedis: HOST, PORT, PASSWORD, REST_TOKEN, REST_URL, REDIS_URL
  • PrivateService: ADDRESS
  • WebService: URL
properties.environment

Environment Variables

Type: Array of EnvironmentVar

A list of environment variables to pass to the script or command.

Values can be:

properties.assumeRoleOfResource

Assume Role of Resource

Type: string

The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.

The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.

Supported Resource Types:

  • function
  • batch-job
  • worker-service
  • web-service
  • private-service
  • multi-container-workload
  • nextjs-web
  • astro-web
  • nuxt-web
  • sveltekit-web
  • solidstart-web
  • tanstack-web
  • remix-web
EnvironmentVarAPI referenceParent:LocalScript
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