Feature: run local scripts from hooks #7

New Issue

2026-05-21T10:13:09Z

dannygroenewegen commented

2026-05-21 10:13:09 +00:00

Use case

Alakazam hooks currently run abra.sh functions. This works well for operations that are generic enough to belong in a recipe. However, I also have custom automations that I want to trigger at the same hooks. These are specific to our situation and don't belong in a recipe's abra.sh.

I'd like to extend the hook system to allow running a local shell script instead of an abra command, so deployment-specific automation can be run from the same hooks.

Proposal

Add a script prefix to hook entries. When alakazam encounters script as the first token, it runs a local shell script instead of calling abra.

Syntax:

initial-hooks:
  - app set_default_quota            # existing, abra hook
  - script ./post-setup.sh              # new, run a local script
  - script ./script.sh -a example   # new, script with arguments

secret-hooks:
  - set_admin_password               # existing, passed to abra app cmd --local
  - script ./generate-token.sh       # new, run a local script

Path resolution: relative paths are resolved against the root path defined in alakazam.yml; absolute paths are used as-is.

Context via environment variables: before running the script, alakazam sets:

ALAKAZAM_APP_DOMAIN e.g. nextcloud.example.com
ALAKAZAM_APP_SERVER e.g. server.example.com
ALAKAZAM_INSTANCE_DOMAIN e.g. example.com

Positional arguments written in the hook entry are passed directly to the script.

Fallback: if the specified script path does not resolve to an existing file, alakazam falls back to treating script as a container name and calls abra normally. This avoids a breaking change if any stack happens to have a container named script.

### Use case Alakazam hooks currently run `abra.sh` functions. This works well for operations that are generic enough to belong in a recipe. However, I also have custom automations that I want to trigger at the same hooks. These are specific to our situation and don't belong in a recipe's `abra.sh`. I'd like to extend the hook system to allow running a local shell script instead of an abra command, so deployment-specific automation can be run from the same hooks. ### Proposal Add a `script` prefix to hook entries. When alakazam encounters `script` as the first token, it runs a local shell script instead of calling abra. **Syntax:** ```yaml initial-hooks: - app set_default_quota # existing, abra hook - script ./post-setup.sh # new, run a local script - script ./script.sh -a example # new, script with arguments secret-hooks: - set_admin_password # existing, passed to abra app cmd --local - script ./generate-token.sh # new, run a local script ``` **Path resolution:** relative paths are resolved against the root path defined in alakazam.yml; absolute paths are used as-is. **Context via environment variables:** before running the script, alakazam sets: - `ALAKAZAM_APP_DOMAIN` e.g. `nextcloud.example.com` - `ALAKAZAM_APP_SERVER` e.g. `server.example.com` - `ALAKAZAM_INSTANCE_DOMAIN` `e.g. example.com` Positional arguments written in the hook entry are passed directly to the script. **Fallback:** if the specified script path does not resolve to an existing file, alakazam falls back to treating `script` as a container name and calls abra normally. This avoids a breaking change if any stack happens to have a container named `script`.

moritz commented

2026-05-26 15:09:43 +00:00

I think it's a good idea, especially if the hooks are customized on a very specific use case. We would mostly try to upstream our customization into abra.sh to make them available for the public. Therefore we would rarely use the script hook and can't guarantee that this won't break by any further changes, as long we haven't a test suite for alakazam.

I think it's a good idea, especially if the hooks are customized on a very specific use case. We would mostly try to upstream our customization into `abra.sh` to make them available for the public. Therefore we would rarely use the `script` hook and can't guarantee that this won't break by any further changes, as long we haven't a test suite for alakazam.

dannygroenewegen referenced this issue

2026-06-01 19:33:27 +00:00

feat: add local script support to hooks #9

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: toolshed/alakazam#7