logoStacktape docs

Hooks

Introduction

  • Hooks allow you to execute a custom command or script before specified command, after specified command or when a specified command fails.
  • Example use cases:
    • build, validate or lint your application before deployment
    • execute database migration after deployment
    • send a notification to a Slack channel after a deployment error

Hook action

  • You can execute either a command or a script.
  • Both of them get the following environment variables:
    • STP_HOOK_TYPE - before, after or onError
    • STP_COMMAND - Stacktape command used

Execute command

  • Executes the specified command in a separate process using default shell.
  • Stdio (standard input/output) will be piped to the Stacktape process.
  • 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 configurted.
hooks:
  - triggers: ["before:deploy"]
    executeCommand: npx gatsby build


resources:
  nextJsApp:
    type: bucket
    properties:
      uploadDirectory:
        directoryPath: public

Execute script

  • 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 configure-defaults command or a default executable on your machine:
    • node for Javascript and Typescript
    • python for Python
  • Only one of executeScript and executeCommand can be configurted.
hooks:
  - triggers: ["onError:deploy"]
    executeScript: scripts/send-slack-notification.ts
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
  });
})();

Hookable events

before:command hooks

  • Executed before the command, but AFTER the configuration has been successfully loaded.
  • Must have the format before:[command].
Executed only if the configuration was successfully loaded and hooks has been registered. The hook won't be executed if there's an error with your CLI arguments or in your configuration.

after:command hooks

  • Executed after the command has successfully finished.
  • For convenience, after:deploy hook can reference parameters of your stack resources in its environment variables (using $ResourceParam() and $CfResourceParam() directives).

onError:command hooks

  • Executed if the command has failed.
  • onError hooks additionaly get the following environment variables STP_ERROR containing data about the error:
    • message: human-readable message
    • errorType: type of the error
    • hints: (for expected errors only) - list of hints that might help you solve the error.
    • errorId: (for unexpected errors only) - you can use this error id to report an issue
Executed only if the configuration was successfully loaded and hooks has been registered. The hook won't be executed if there's an error with your CLI arguments or in your configuration.

API reference

LifecycleHook  API reference
triggers
Required

List of events that will trigger this hook

Type: Array of string ENUM

Possible values: after:compile-templateafter:deleteafter:deployafter:invoke-cloudafter:invoke-localafter:logsafter:package-workloadsafter:preview-changesafter:rollbackafter:stack-infoafter:userpool-create-userafter:userpool-get-tokenbefore:compile-templatebefore:deletebefore:deploybefore:invoke-cloudbefore:invoke-localbefore:logsbefore:package-workloadsbefore:preview-changesbefore:rollbackbefore:stack-infobefore:userpool-create-userbefore:userpool-get-tokenonError:compile-templateonError:deleteonError:deployonError:invoke-cloudonError:invoke-localonError:logsonError:package-workloadsonError:preview-changesonError:rollbackonError:stack-infoonError:userpool-create-useronError:userpool-get-token

  • Format is {before or after}:{stacktape command}.
  • Example: before:deploy

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 configure-defaults command or a default executable on your machine:
    • node for Javascript and Typescript
    • python for Python
  • Only one of executeScript and executeCommand can be configurted.

executeCommand

Terminal command to execute

Type: string

  • Executes the specified command in a separate process using default shell.
  • Stdio (standard input/output) will be piped to the Stacktape process.
  • 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 configurted.

environment

Environment variables passed to the command.

Type: Array of EnvironmentVar

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: false

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

Type: boolean

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

EnvironmentVar  API reference
Parent API reference: LifecycleHook
name
Required

Name of the environment variable

Type: string

value
Required

Value of the environment variable

Type: (string or number or boolean)