Hook

A hook is an instance of a Command that is executed when a certain event triggers.

You can find more information on how hooks work and how to use them in the corresponding section of the user documentation: Hooks.

Schema

The Schema defines what the contents of the YAML configuration files are.

classmethod schema() → schema.Schema
[$name]: str

Name as specified in the key of the parent app.

Added by system. DO NOT specify this yourself in the YAML files.

events: List[str]

List of events that trigger this hook.

[continue_on_error]: bool

Defaults to False. If True the hook will interrupt (in most cases, some Git Hooks always ignore failure) whatever process caused it to trigger and fail with an error. Any further hook is not executed. This will cause riptide hook-trigger to exit with a non-zero exit code. If this is False, any error is ignored.

[pass_event_arguments]: bool

Defaults to true. If True, arguments related to the event are passed to the command, if False, they are not. If and what arguments would be passed depends on the event, see documentation.

[working_directory]: str

Working directory for the hook command, relative to the src specified in the project

If not given, the command is executed in the src directory.

command:

This can take two forms:

  1. Command definition

    run: Command

    A Command object.

    Riptide will trigger this command like Riptide executes any Command under any other circumstance.

  2. Command from App

    from_app: str

    Key of a command defined in the app, must exist.

    [args]: str

    Additional arguments to pass to the command. These are passed before event arguments (see pass_event_arguments).

    When using the “command from app” form, Riptide will execute the command defined in the app like normal and optionally pass the list of arguments to it. They will be passed as-is as if they were typed on the command line by bash, and parsed as such.

    This form is not allowed for hooks which are globally defined. Trying to use such a hook in the riptide.config.document.config.Config will result in Riptide refusing to operate.

Example Document:

hook:
  events:
    - git-pre-commit
    - post-start
    - custom-post-magic
  continue_on_error: true
  working_directory: www
  command:
    run:
      $ref: /command/my_check

List of events

What follows is a list of defined hooks in the latest Riptide release. The keys to be used in hook configuration files are the strings next to the identifier. For PreStart you will find that this is pre-start. It is also always possible to configure and trigger custom hooks using the custom- prefix.

class HookEvent(key: str)

Bases: enum.Enum

An event that triggers hooks.

In addition to events listed, custom events can be used with the prefix custom-, these can be triggered by riptide hook-trigger.

Initialization

PreStart

‘pre-start’

Hook is run before Riptide starts services when using riptide start or riptide restart.

Warning

Hooks are NOT executed if the Proxy Server starts a project. Please consider the pre_start attribute of services for important pre-start commands. riptide start-fg does not trigger this event for interactive services.

Parameters:

  • Comma-seperated list of names that are about to be started

PostStart

‘post-start’

Hook is run after Riptide started services when using riptide start or riptide restart.

Warning

Hooks are NOT executed if the Proxy Server starts a project. Please consider the post_start attribute of services for important post-start commands. riptide start-fg does not trigger this event for interactive services.

Parameters:

  • Comma-seperated list of names that were requested to be started and are now started

PreStop

‘pre-stop’

Hook is run before Riptide stops services when using riptide stop or riptide restart.

Warning

Hooks are NOT executed if the Proxy Server stops a project.

Parameters:

  • Comma-seperated list of names that are about to be stopped

PostStop

‘post-stop’

Hook is run after Riptide stopped services when using riptide stop or riptide restart (or another command that switched the environment).

Warning

Hooks are NOT executed if the Proxy Server stops a project.

Parameters:

  • Comma-seperated list of names that are now stopped (including services that were already stopped)

PreDbSwitch

‘pre-db-switch’

Hook is run before Riptide switches database environments when using riptide db-switch (or another command that switched the environment).

Parameters:

  • Currently active database environment name

  • Database environment name requested to switch to

PostDbSwitch

‘post-db-switch’

Hook is run before Riptide switches database environments when using riptide db-switch.

Parameters:

  • Name of database environment that was switched to

PreDbNew

‘pre-db-new’

Hook is run before Riptide created a new blank database environment when using riptide db-new.

Parameters:

  • Name of database environment that is about to be created

PostDbNew

‘post-db-new’

Hook is run after Riptide created a new blank database environment when using riptide db-new, but before Riptide has switched to this new environment.

Parameters:

  • Name of database environment that was created

PreDbImport

‘pre-db-import’

Hook is run before Riptide imports a file into a database environment when using riptide db-import or riptide setup.

Parameters:

  • Currently active database environment name

  • Path to the file to import (for hook commands this file is mounted)

PostDbImport

‘post-db-import’

Hook is run after Riptide imported a file into a database environment when using riptide db-import.

Parameters:

  • Currently active database environment name

  • Path to the imported file (for hook commands this file is mounted)

PreDbExport

‘pre-db-export’

Hook is run before Riptide exports a file from a database environment when using riptide db-export.

Parameters:

  • Database environment name

PostDbExport

‘post-db-export’

Hook is run after Riptide exported a file from a database environment when using riptide db-export.

Parameters:

  • Database environment name

  • Path to the file that contains the exported data (for hook commands this file is mounted)

PreDbCopy

‘pre-db-copy’

Hook is run before Riptide copied a database environment when using riptide db-copy.

Parameters:

  • Name of database environment that is being copied from

  • Name of database environment that is being copied to

PostDbCopy

‘post-db-copy’

Hook is run after Riptide copied a database environment when using riptide db-new, but before Riptide has switched to this new environment.

Parameters:

  • Name of database environment that was being copied from

  • Name of database environment that was being copied to

PreFileImport

‘pre-file-import’

Hook is run before Riptide imports a file into the project when using riptide import-files.

Parameters:

  • Key of the import definition

  • Path to the file to import (for hook commands this file is mounted)

PostFileImport

‘post-file-import’

Hook is run after Riptide imported a file into the project when using riptide import-files or riptide setup.

Parameters:

  • Key of the import definition

  • Path to the imported file (for hook commands this file is mounted)

PostUpdate

‘post-update’

Hook is run after Riptide processed image and repo updates when using riptide update.

Parameters: none

PostSetup

‘post-setup’

Hook is run at the end of the interactive setup wizard when using riptide setup.

Parameters:

  • new-project if the wizard was run in “new project” mode, existing-project otherwise

GitApplypatchMsg

‘git-applypatch-msg’

Hook is run when Git triggers a applypatch-msg Git Hook. Riptide forwards all arguments and environment variables that Git provides to the hook. See documentation.

GitPreApplypatch

‘git-pre-applypatch’

Hook is run when Git triggers a pre-applypatch Git Hook. See documentation of git-applypatch-msg for more information.

GitPostApplypatch

‘git-post-applypatch’

Hook is run when Git triggers a post-applypatch Git Hook. See documentation of git-applypatch-msg for more information.

GitCommitMsg

‘git-commit-msg’

Hook is run when Git triggers a commit-msg Git Hook. See documentation of git-applypatch-msg for more information.

GitPreCommit

‘git-pre-commit’

Hook is run when Git triggers a pre-commit Git Hook. See documentation of git-applypatch-msg for more information.

GitPostCommit

‘git-post-commit’

Hook is run when Git triggers a post-commit Git Hook. See documentation of git-applypatch-msg for more information.

GitPrepareCommitMsg

‘git-prepare-commit-msg’

Hook is run when Git triggers a prepare-commit-msg Git Hook. See documentation of git-applypatch-msg for more information.

GitPostCheckout

‘git-post-checkout’

Hook is run when Git triggers a post-checkout Git Hook. See documentation of git-applypatch-msg for more information.

GitPreRebase

‘git-pre-rebase’

Hook is run when Git triggers a pre-rebase Git Hook. See documentation of git-applypatch-msg for more information.

GitPreAutoGc

‘git-pre-auto-gc’

Hook is run when Git triggers a pre-auto-gc Git Hook. See documentation of git-applypatch-msg for more information.

GitPrePush

‘git-pre-push’

Hook is run when Git triggers a pre-push Git Hook. See documentation of git-applypatch-msg for more information.

GitPostRewrite

‘git-post-rewrite’

Hook is run when Git triggers a post-rewrite Git Hook. See documentation of git-applypatch-msg for more information.

GitPostMerge

‘git-post-merge’

Hook is run when Git triggers a post-merge Git Hook. See documentation of git-applypatch-msg for more information.

key: str

None

classmethod try_from_key(key: str) → riptide.hook.event.HookEvent | None
classmethod try_any_from_key(key: str) → riptide.hook.event.AnyHookEvent | None
classmethod git_events() → Sequence[riptide.hook.event.HookEvent]
static validate(event: Any) → riptide.hook.event.AnyHookEvent | None

Checks that a hook event is known (or custom), returns the corresponding hook enum or custom event string, if valid.

static is_custom(event: riptide.hook.event.AnyHookEvent) → TypeGuard[str]
static key_for(event: riptide.hook.event.AnyHookEvent) → str