Hooks



Hooks allow you to execute a custom command or script before or after a specified Stacktape command.

Example use cases:

  • Building, validating, or linting your application before deployment.
  • Running unit tests before deployment.
  • Executing database migrations after deployment.
  • Cleaning up a database before deletion.

How to use hooks

You can reference scripts defined in the scripts section of your stacktape.yml file within a hook. Scripts can also be executed manually. For more information, see the scripts documentation.

When a script is executed, it receives the following environment variables:

  • STP_HOOK_TYPE: before or after
  • STP_COMMAND: The Stacktape command that was used

These are in addition to the environment variables specified in the script definition and those injected when using connectTo.

NamedScriptLifecycleHookAPI referenceParent:Hooks
scriptNameRequired

Script Name

Type: string

The name of the script to execute. The script must be defined in the scripts section of your configuration.

skipOnCI

Skip this hook in CI/CD environments (CodeBuild, GitHub Actions, GitLab CI).

Type: boolean

Useful for hooks that only make sense locally (e.g., opening a browser, interactive prompts).

skipOnLocal

Skip this hook when running locally; only run in CI/CD.

Type: boolean

Useful for CI-only tasks (e.g., uploading test reports, notifying Slack).

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

hooks:
  beforeDeploy:
    - scriptName: buildWeb

Hookable events

HooksAPI reference
beforeDeploy

Scripts to run before deploying. Common use: build frontend, lint code.

Type: Array of NamedScriptLifecycleHook

afterDeploy

Scripts to run after deploying. Common use: run database migrations, seed data.

Type: Array of NamedScriptLifecycleHook

beforeDelete

Scripts to run before deleting the stack. Common use: export data, clean up external resources.

Type: Array of NamedScriptLifecycleHook

Only runs when --configPath and --stage are provided to the delete command.

afterDelete

Scripts to run after deleting the stack.

Type: Array of NamedScriptLifecycleHook

Only runs when --configPath and --stage are provided to the delete command.

beforeBucketSync

Scripts to run before syncing bucket contents.

Type: Array of NamedScriptLifecycleHook

afterBucketSync

Scripts to run after syncing bucket contents.

Type: Array of NamedScriptLifecycleHook

beforeDev

Scripts to run before starting dev mode.

Type: Array of NamedScriptLifecycleHook

afterDev

Scripts to run after dev mode exits.

Type: Array of NamedScriptLifecycleHook

Before-command hooks

These hooks are executed before the specified command, but after the configuration has been successfully loaded.

A before-command hook is only executed if the configuration is loaded successfully and the hooks are registered. The hook will not be executed if there is an error in your CLI arguments or in your configuration file.

After-command hooks

These hooks are executed after the specified command has finished successfully. Common use cases for after-command hooks include database migration or seeding, and API or endpoint testing.

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