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 (falls back to CM_DEPLOYMENT_SLACK_WEBHOOK_URL in config.rb)	https://hooks.slack.com/services/...
HATCHBOX_APP_ID + LOG_ID	"View Hatchbox Log" button	Provided by Hatchbox
HATCHBOX_SERVER_NAME	Server name shown in the config-not-available notice (needs ~/.asdf-vars sourced)	staging-web-1
RAILS_ENV	Environment name shown in the notification	staging → "Staging"
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
    CM_DEPLOYMENT_SLACK_WEBHOOK_URL = 'https://hooks.slack.com/services/...'

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

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

Set SLACK_WEBHOOK_URL in your Hatchbox environment variables to use a different Slack channel/workspace. If unset, the CM_DEPLOYMENT_SLACK_WEBHOOK_URL constant is used.

Config Not Available

A notification needs APP_NAME, APP_URL and SLACK_WEBHOOK_URL. As soon as the config is loaded, the scripts check for these values. If any is blank for the current environment, they post a single Slack message and exit without sending the usual started/complete/failed notification:

⚠️ Deployment notification config for Staging is not available. These values need to be updated for this environment: • APP_NAME • APP_URL 🖥 Server: staging-web-1

Set the missing values under Environment Variables in the Hatchbox dashboard for that environment. SLACK_WEBHOOK_URL counts as configured when it falls back to CM_DEPLOYMENT_SLACK_WEBHOOK_URL.

The message includes an Environment Variables button that opens the app's env-vars page (https://hatchbox.io/apps/<APP_ID>/env_vars) — the URL is built the same way as the "View Hatchbox Log" button's.

The server name comes from HATCHBOX_SERVER_NAME, which Hatchbox only exposes after ~/.asdf-vars is sourced — the hook scripts do this when the file exists. If it isn't available, the line is omitted.

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 Slack notifications with the following format:

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

If the environment's config isn't available, a "Deployment Notification Config Not Available" message is sent instead and the script exits — see Config Not Available.