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)

The mechanism is content-agnostic — it copies whatever is inside deploy-config/ and tracks the directory checksum via SHA256. Updating cm-admin in your Gemfile automatically brings the new checksum along — the boot check shows the difference with no extra work:

1. Bump cm-admin in your Gemfile and run bundle update cm-admin
2. If the boot warning appears (marker checksum differs from the gem's deploy-config/ checksum), run rake cm_admin:deploy_config:sync
3. Commit the config folder changes

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.

Auto-Detected from Hatchbox

Variable	Source	Example
App Name	Rails.configuration.x.project_settings.name	"Uddhava Staging"
Environment	RAILS_ENV	staging → "Staging"
Hatchbox URL	HATCHBOX_APP_ID + LOG_ID	Built automatically
Slack Webhook	SLACK_WEBHOOK_URL env var (falls back to default in config.rb)	https://hooks.slack.com/services/...

Configuration

lib/config.rb - the Slack webhook is read from the SLACK_WEBHOOK_URL environment variable, falling back to the CM_DEPLOYMENT_SLACK_WEBHOOK_URL constant:

module Hatchbox
  module Config
    CM_DEPLOYMENT_SLACK_WEBHOOK_URL = 'https://hooks.slack.com/services/...'

    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.

APP_URL - auto-detected from the be_url credential inside lib/config.rb for the "View Application" button:

APP_URL=https://myapp.example.com

If not set, the button simply won't appear in the Slack notification.

Skipping Notifications

Set deployment_alerts to false in your cm-admin initializer to stop deployment notifications from being sent during Hatchbox builds:

# config/initializers/cm_admin.rb
CmAdmin.configure do |config|
  config.deployment_alerts = false
end

When disabled, hatchbox_notification.rb detects the setting via CmAdmin.config.deployment_alerts and 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                  # Edit CM_DEPLOYMENT_SLACK_WEBHOOK_URL here
│   ├── event_types.rb             # Slack payload definitions (don't touch)
│   └── hatchbox_notification.rb   # Notification entrypoint, run via bin/rails runner (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 (only if APP_URL is set)