Hatchbox Deployment Scripts

Version-control your Hatchbox build/deploy scripts. Hatchbox auto-detects these scripts during deployment.

Setup

1. Run rake cm_admin:deploy_config:sync in your app to copy .hatchbox/ to the app root (this also records the checksum marker .deploy-config)
2. Commit the changes and remove scripts from the Hatchbox dashboard

Keeping Config in Sync

Hatchbox reads .hatchbox/ from the deployed app's git repo — gems installed via Bundler are never scanned. So when you update the cm-admin gem and its bundled config changes, sync it into your app:

rake cm_admin:deploy_config:sync

The gem stores all deploy config files in a deploy-config/ directory at the gem root. The sync task copies everything inside deploy-config/ to your app root and writes a .deploy-config marker file tracking a SHA256 checksum of the bundled config.

Mechanism	When it runs	Behavior
rake cm_admin:deploy_config:sync	Manual, after each cm-admin gem update	Copies everything from the gem's deploy-config/ directory into the app root and writes the checksum marker (.deploy-config at app root)
App boot check (development)	Every boot	Warns like the pending-migrations alert when the marker checksum differs from the gem's deploy-config/ checksum — sync is never done automatically
rake cm_admin:deploy_config:check	CI	Fails the build when config is out of date (add after bundle update cm-admin)

To add new deploy config files in the future, just drop them into deploy-config/ in the gem source — no code changes needed. The checksum changes automatically and all apps will get the sync warning on next boot.

After syncing, commit the changes before deploying — Hatchbox picks them up from git, not from a boot-time copy.

Environment Variables

Variable	Used for	Example
APP_NAME	App name shown in the notification message	Uddhava Staging
APP_URL	"View Application" button	https://myapp-staging.com
SLACK_WEBHOOK_URL	Slack webhook to post to	https://hooks.slack.com/services/...
HATCHBOX_APP_ID + LOG_ID	"View Hatchbox Log" button	Provided by Hatchbox
DEPLOYMENT_ALERTS	Set to false to skip notifications entirely	true

Configuration

lib/config.rb - every value is read from the environment, so the scripts stay independent of the host app:

module Hatchbox
  module Config
    def self.app_name
      ENV.fetch('APP_NAME', nil)
    end

    def self.slack_webhook
      ENV.fetch('SLACK_WEBHOOK_URL', nil)
    end
  end
end

Set SLACK_WEBHOOK_URL in your Hatchbox environment variables to the Slack channel/workspace you want to post to. If unset, deployment notifications are skipped and the script warns that the variable isn't set.

Skipping Notifications

Set DEPLOYMENT_ALERTS to false in your Hatchbox environment variables to stop deployment notifications from being sent during Hatchbox builds:

DEPLOYMENT_ALERTS=false

When it's disabled, hatchbox_notification.rb exits before sending any Slack notification. This is useful for suppressing notifications in certain environments (e.g. CI builds, preview apps).

Files

.hatchbox/
├── lib/
│   ├── config.rb                  # Env-var values for the notifications (APP_NAME, APP_URL, etc.)
│   ├── event_types.rb             # Slack payload definitions (don't touch)
│   └── hatchbox_notification.rb   # Notification entrypoint, run via ruby (don't touch)
├── pre-build                      # Deployment started
├── post-deploy                    # Deployment complete
└── failed-deploy                  # Deployment failed

Slack Notification Format

The scripts send compact Slack notifications with the following format:

• Title: Deployment status header (Deployment Started, Deployment Complete, Deployment Failed)
• Message: One line with the app name and status (e.g., "⏳ Uddhava - Staging has started to deploy via Hatchbox.")
• Buttons:
  • "View on Hatchbox" - Links to the Hatchbox deployment log page
  • "View Application" - Links to the deployed app (APP_URL)