Hooks & Scripts

Configure lifecycle hooks and custom scripts for your environments.

Hooks Overview

Hooks run at specific points in the environment lifecycle:

Hook	When It Runs
`post_checkout`	After code is cloned
`post_create`	After environment is created
`pre_start`	Before services start
`post_start`	After services are running
`pre_destroy`	Before environment is destroyed

Basic Hook Configuration


hooks:
  post_checkout:
    - command: pnpm install
      workdir: /home/dev/myapp
 
  post_start:
    - command: pnpm db:seed
      workdir: /home/dev/myapp/api

Full Hook Configuration


hooks:
  post_checkout:
    - command: pnpm install
      workdir: ${PROJECT_PATH}
      env:
        CI: "true"
 
  post_create:
    - command: ./scripts/setup-env.sh
      workdir: /home/dev/myapp
      run_as: root
      condition: "!file_exists(.env)"
 
  pre_start:
    - command: pnpm build
      workdir: /home/dev/myapp/web
      timeout: 300                    # 5 minutes
 
  post_start:
    - command: pnpm db:migrate
      workdir: /home/dev/myapp/api
      depends_on:
        - mongodb
 
    - command: pnpm db:seed
      workdir: /home/dev/myapp/api
      condition: database.mode == "local"
 
  pre_destroy:
    - command: ./scripts/backup.sh
      workdir: /home/dev/myapp

Hook Properties

Property	Description
`command`	Command to execute
`workdir`	Working directory
`env`	Environment variables
`run_as`	User to run as (dev or root)
`condition`	Conditional execution
`timeout`	Maximum execution time (seconds)
`depends_on`	Wait for services
`continue_on_error`	Don’t fail if hook fails

Variables in Hooks

Use these variables in hooks:

Variable	Description
`${PROJECT_PATH}`	Project root path
`${APP_PATH}`	Current app path
`${GENBOX_NAME}`	Environment name
`${PROFILE}`	Profile name


hooks:
  post_checkout:
    - command: echo "Setting up ${GENBOX_NAME}"
      workdir: ${PROJECT_PATH}

Conditional Hooks

Run hooks based on conditions:


hooks:
  post_start:
    # Only if database was copied
    - command: pnpm db:migrate
      condition: database.mode == "copy"
 
    # Only if specific app is included
    - command: pnpm seed
      condition: apps.api
 
    # Only if file doesn't exist
    - command: ./init-config.sh
      condition: "!file_exists(.env.local)"
 
    # Environment-based
    - command: ./setup-dev.sh
      condition: profile == "development"

Hook Dependencies

Wait for services before running:


hooks:
  post_start:
    - command: pnpm db:migrate
      depends_on:
        - mongodb                     # Wait for MongoDB
        - redis                       # Wait for Redis
 
    - command: pnpm test:integration
      depends_on:
        - api                         # Wait for API to be healthy

Scripts Section

For reusable scripts with explicit stages:


scripts:
  - name: setup-database
    path: ./scripts/setup-db.sh
    stage: post_create
    description: Initialize database schema
    run_as: dev
 
  - name: build-frontend
    path: ./scripts/build.sh
    stage: build
    description: Build frontend assets
    depends_on:
      - install-deps
 
  - name: install-deps
    path: ./scripts/install.sh
    stage: setup
    run_as: dev

Script Stages

Stage	When
`setup`	During initial setup
`build`	During build phase
`start`	During service startup
`post-start`	After services are running

Error Handling


hooks:
  post_start:
    # Continue even if this fails
    - command: pnpm optional-setup
      continue_on_error: true
 
    # This will run regardless
    - command: pnpm required-setup

Common Hook Patterns

Install Dependencies


hooks:
  post_checkout:
    - command: pnpm install --frozen-lockfile
      workdir: /home/dev/myapp
      env:
        CI: "true"

Database Setup


hooks:
  post_start:
    - command: pnpm db:migrate
      workdir: /home/dev/myapp/api
      depends_on:
        - mongodb
 
    - command: pnpm db:seed
      workdir: /home/dev/myapp/api
      condition: database.mode == "local"

Build Assets


hooks:
  pre_start:
    - command: pnpm build
      workdir: /home/dev/myapp/web
      timeout: 300

Docker Compose Services


hooks:
  post_start:
    - command: docker-compose up -d
      workdir: /home/dev/myapp/api
      condition: apps.api

Pre-destroy Backup


hooks:
  pre_destroy:
    - command: mongodump --out=/tmp/backup
      workdir: /home/dev/myapp

Debugging Hooks

View hook execution:


# Watch creation including hooks
gb create my-env --profile full -w
 
# Check logs
gb connect my-env -c "cat /var/log/genbox/hooks.log"

Best Practices

Keep hooks idempotent: Safe to run multiple times
Add timeouts: Prevent hung processes
Use conditions: Avoid unnecessary execution
Log output: Add echo statements for debugging
Handle errors: Use continue_on_error wisely
Order dependencies: Use depends_on for service dependencies