Skip to content

Defined Hooks

🛠️ Tools · ⬅ Top

Context hook runners

These run within the current project regardless of where Zesk Build is loaded:

hookVersionCurrent

Application current version

Usage

hookVersionCurrent  [ --help ] [ --home home ] arguments ...

Application current version

Extracts the version from the repository

Arguments

  • --help - Optional. Flag. Display this help.
  • --application application - Optional. Directory. Application home directory.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

hookVersionLive

Application deployed version

Usage

hookVersionLive  [ --help ] [ --home home ] arguments ...

Application deployed version

Arguments

  • --help - Optional. Flag. Display this help.
  • --application application - Optional. Directory. Application home directory.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Application hooks

Arguments

  • --sound soundName - Play a sound
  • --title title - Set the title of the notification
  • message ... - Display this message (one per line) in the notification.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_NOTIFY_SOUND - String. Sound for notifications. Set to - for no sound. Defaults to zesk-build-notification.
  • Play this sound if none is specified.

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Version hooks

These hooks interact with release-new.sh and deployment tools but are intended to be used anywhere.

  • version-current - Required. The current version. Defaults to the highest version in docs/release.
  • version-live - Optional. Determine the live version.
  • version-created - Optional. Run when a new version is created.
  • version-already - Optional. Run when a new version is requested, but it already exists in the source code.

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_VERSION_NO_OPEN - Boolean. Constant for whether to open release notes when a version is requested (see version-already)
  • Do not open in the default editor. Set this is you do not want the behavior and do not have an override version-created hook

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_VERSION_NO_OPEN - Boolean. Constant for whether to open release notes when a version is requested (see version-already)
  • Do not open in the default editor. Set this is you do not want the behavior and do not have an override version-created hook

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

catchReturn catchEnvironment muzzle pushd cd printf versionSort popd usageDocument

__hookVersionLive

Fetch the current live version of the software using GitHub

Usage

__hookVersionLive

Fetch the current live version of the software using GitHub APIs

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

Development Hooks

__hookProjectActivate

The project-activate hook runs when this project is activated in

Usage

__hookProjectActivate [ otherHomeDirectory ]

The project-activate hook runs when this project is activated in the console (and another project was previously active) Implementations MUST overwrite environment variables which MUST change here or MUST be active here to work, etc. This is NOT like other hooks in that it is run as hookSource

Arguments

  • otherHomeDirectory - The old home directory of the project

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • approve - Report on all approvals during project activation
  • approve-verbose - Display verbose approval messages

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

__hookProjectActivate

The project-activate hook runs when this project is activated in

Usage

__hookProjectActivate [ otherHomeDirectory ]

The project-activate hook runs when this project is activated in the console (and another project was previously active) Implementations MUST overwrite environment variables which MUST change here or MUST be active here to work, etc. This is NOT like other hooks in that it is run as hookSource

Arguments

  • otherHomeDirectory - The old home directory of the project

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • approve - Report on all approvals during project activation
  • approve-verbose - Display verbose approval messages

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Deployment Hooks

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

__hookApplicationID

Generate a unique ID for the state of the application files

The default hook uses the short git sha:

git rev-parse --short HEAD

Arguments

  • none

Examples

885acc3

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

hookRun maintenance

Toggle maintenance on or off. The default version of this

Usage

hookRun maintenance maintenanceSetting [ --message maintenanceMessage ]

Toggle maintenance on or off. The default version of this modifies the environment files for the application by modifying the .env.local file and dynamically adding or removing any line which matches the MAINTENANCE variable.

Note that applications SHOULD load this configuration file dynamically (and monitor it for changes) to enable maintenance at any time.

Arguments

  • maintenanceSetting - Required. String. Maintenance setting: on | 1 | true | enable | off | 0 | false | disable
  • --message maintenanceMessage - Optional. String. Message to display to the use as to why maintenance is enabled.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_MAINTENANCE_VARIABLE - EnvironmentVariable. The variable
  • If you want to use a different environment variable than MAINTENANCE, set this environment variable to the variable you want to use.

Arguments

  • none

Examples

  • Move directories to make deployment final

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

hookRun deploy-activate applicationPath

This is called where the current working directory at the time of running is the new application and the applicationPath which is passed as an argument is the place where the new application should be moved to in order to activate it.

Return Code: 0 - This is called to replace the running application in-place

Arguments

  • applicationPath - This is the target for the current application

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Examples

  • Enable a health endpoint which returns version number and ensure all servers return the same version number (which was just updated)
  • Check the home page for a version number
  • Check for a known artifact (build sha) in the server somehow
  • etc.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Examples

  • Move directories to make deployment final

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Git hooks

Pre-commit

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • bashSanitize - Debug the patterns used to exclude files by bashSanitize

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • --read-only - Flag. Optional. Make all files read-only instead of writable by user.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Post-commit

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Test Hooks

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error