Skip to content

Defined Hooks

🛠️ Tools · ⬅ Home

Context hook runners

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

Usage

hookVersionCurrent [ --help ] [ --application application ]

Application current version Extracts the version from the repository

Arguments

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

Return codes

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

Usage

hookVersionLive [ --help ] [ --application application ]

Application deployed version

Arguments

  • --help - Flag. Optional. Display this help.
  • --application application - Directory. Optional. 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

Application Hooks

hookRun application-environment

application-environment hook default implementation

Usage

hookRun application-environment

Hook to customize the application environment file

Arguments

  • none

Return codes

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

hookRun application-files

application-files hook default implementation

Usage

hookRun application-files [ ... ] [ --debug ] [ --not ]

Get a complete list of files which make up an application's state. Should include anything which is code, not design. (fine line)

Arguments

  • ... - Arguments. Optional. Arguments are passed to the find command.
  • --debug - Flag. Optional. Show debugging information.
  • --not - Flag. Optional. Show list of files which are still excluded by APPLICATION_CODE_IGNORE but show files which are NOT included by extension.

Return codes

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

hookRun application-environment

application-environment hook default implementation

Usage

hookRun application-environment

Hook to customize the application environment file

Arguments

  • none

Return codes

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

hookRun application-id

application-id hook default implementation

Usage

hookRun application-id [ --help ]

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

  • --help - Flag. Optional. Display this help.

Examples

885acc3

Return codes

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

hookRun application-tag

application-tag hook default implementation

Usage

hookRun application-tag

Get the "tag" (or current display version) for an application The default hook uses most recent tag associated in git or v0.0.1 if no tags exist.

Arguments

  • none

Return codes

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

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 - String. Required. Maintenance setting: on | 1 | true | enable | off | 0 | false | disable
  • --message maintenanceMessage - String. Optional. 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.

Development Hooks

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

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

hookRun application-environment

application-environment hook default implementation

Usage

hookRun application-environment

Hook to customize the application environment file

Arguments

  • none

Return codes

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

hookRun application-id

application-id hook default implementation

Usage

hookRun application-id [ --help ]

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

  • --help - Flag. Optional. Display this help.

Examples

885acc3

Return codes

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

hookRun application-tag

application-tag hook default implementation

Usage

hookRun application-tag

Get the "tag" (or current display version) for an application The default hook uses most recent tag associated in git or v0.0.1 if no tags exist.

Arguments

  • none

Return codes

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

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 - String. Required. Maintenance setting: on | 1 | true | enable | off | 0 | false | disable
  • --message maintenanceMessage - String. Optional. 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 - This SHOULD exit successfully always

Arguments

  • applicationPath - Directory. Required. This is the target for the current application

Return codes

  • 0 - This is called to replace the running application in-place

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 - Continue with deployment
  • Non-zero - Any non-zero exit code will run deploy-revert hook on all systems and cancel deployment

Arguments

  • none

Return codes

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

Arguments

  • none

Examples

  • Move directories to make deployment final

Return codes

  • 0 - This SHOULD exit successfully always

Arguments

  • none

Return codes

  • 0 - This SHOULD exit successfully always

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 - If the test setup was successful
  • Non-Zero - Any error will terminate testing

Arguments

  • none

Return codes

  • 0 - If the tests all pass
  • Non-Zero - If any test fails for any reason

Arguments

  • none

Return codes

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