Introduction

Scripts are used to execute your custom scripts - either shell commands or scripts written in Javascript, Typescript or Python.
Scripts are executed either by script:run command or inside a hook.
Benefits of running scripts using Stacktape instead of directly:
- Scripts can be reused by all your team members.
- You can inject the result of a directive to the script's environment variable.
Scripts are executed on the same host from which the stacktape command was executed. If you want to execute a script remotely as a part of the stack operation, use a stack-script.

Defining script action

The script must define either executeCommand or executeScript property.

executeCommand

Executes the specified command in a separate process using default shell.
The command will be executed on the machine running the Stacktape command. If the command works on your machine, it doesn't mean it works for people or machines with different OSes or shells.
Only one of executeScript and executeCommand can be configured.

Copy
scripts:
  buildWeb:
    executeCommand: npx gatsby build

executeScript

The script can be written in Javascript, Typescript or Python.
The script is executed in a separate process.
The script is executed using an executable configured using defaults:configure command or a default executable on your machine:
- node for Javascript and Typescript
- python for Python
Only one of executeScript and executeCommand can be configured.

Copy
scripts:
  sendSlackNotification:
    executeScript: scripts/send-slack-notification.ts

Copy
import { WebClient } from "@slack/web-api";

// An access token (from your Slack app or custom integration - xoxp, xoxb)
const token = "my-access-token";
// This argument can be a channel ID, a DM ID, a MPDM ID, or a group ID
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
  });
})();

Executing script

The script can be executed in 2 ways:

using script:run command

Copy
stacktape script:run --scriptName <<scriptName>>

inside a hook

Environment

Most commonly used types of environment variables:

Static - string, number or boolean (will be stringified).
Result of a custom directive.
Referenced property of another resource (using $ResourceParam directive). To learn more, refer to referencing parameters guide.
Value of a secret (using $Secret directive).


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

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

API reference

Script API reference

executeScript

Path to the script to execute

Type: string

The script can be written in Javascript, Typescript or Python.
The script is executed in a separate process.
The script is executed using an executable configured using defaults:configure command or a default executable on your machine:
- node for Javascript and Typescript
- python for Python
Only one of executeScript and executeCommand can be configured.

executeCommand

Terminal command to execute

Type: string

Executes the specified command in a separate process using default shell.
The command will be executed on the machine running the Stacktape command. If the command works on your machine, it doesn't mean it works for people or machines with different OSes or shells.
Only one of executeScript and executeCommand can be configured.

environment

Environment variables passed to the command.

Type: Array of EnvironmentVar

Most commonly used types of environment variables:

Static - string, number or boolean (will be stringified).
Result of a custom directive.
Referenced property of another resource (using $ResourceParam directive). To learn more, refer to referencing parameters guide.
Value of a secret (using $Secret directive).

cwd

Directory where the command will be executed.

Type: string

By default, the script is executed from the directory where the stacktape command was executed.

pipeStdio

Default: true

Pipes stdio (standard input/output) of the hook process to the main process

Type: boolean

This allows you to see logs (stdout/stderr) produced by your hook and respond to prompts.

EnvironmentVar API reference

Parent API reference: Script

name

Required

Name of the environment variable

Type: string

value

Required

Value of the environment variable

Type: (string or number or boolean)