Getting started
Reference
Pre-deploy Steps

Pre-deploy Steps

Overview

Pre-deploy steps are tasks that automatically run before every deployment. They are created from Commands and execute sequentially in the order you specify. If any pre-deploy step fails, the entire deployment is aborted.

Purpose and Benefits

  • Database Migrations: Run schema changes before new code is deployed
  • Smoke Tests: Validate application startup and critical functionality
  • Data Preparation: Prepare data or caches before the new version goes live
  • No Deployment Delays: Pre-deploy tasks run independently of ECS rollout timing, so they can take as long as needed without affecting deployment timeouts
  • Ordered Execution: Control the sequence of operations with drag-and-drop reordering in the UI
  • Fail-Safe: Deployments are blocked if any pre-deploy step fails, preventing broken releases

How Pre-deploy Steps Work

  1. Triggered Automatically: When a deployment starts, all pre-deploy steps run before any containers are updated
  2. Sequential Execution: Steps run in their configured order (by position)
  3. Blocking on Failure: If any step fails, the deployment is aborted immediately
  4. Independent Timing: Steps run as ECS tasks with no connection to deployment timeout limits

CLI Usage

Create Pre-deploy Step 

tapit  create predeploy_step name=command-name

Creates a pre-deploy step that will run the specified command before every deployment.

Required Parameters

  • name: The name of an existing Command to run as a pre-deploy step

Example 

# First, create a command for database migrations
tapit create command name=db-migrate 'rails db:migrate' description='Run database migrations'

# Then add it as a pre-deploy step
tapit create predeploy_step name=db-migrate

List Pre-deploy Steps 

tapit  list predeploy_steps

Shows all configured pre-deploy steps with their position and associated command.

Example Output 

Position  Command Name    Command
1         db-migrate      rails db:migrate
2         smoke-test      rails runner 'AppHealthCheck.verify!'

Delete Pre-deploy Step 

tapit  delete predeploy_step name=command-name

Removes a pre-deploy step. The underlying command is not deleted.

Required Parameters

  • name: The name of the command associated with the pre-deploy step to remove

Web Interface

Pre-deploy steps can be managed from the App Settings menu under Pre-deploy steps:

  • Add Steps: Select from existing commands to add as pre-deploy steps
  • Reorder Steps: Drag and drop to change the execution order
  • Remove Steps: Delete steps that are no longer needed

Common Use Cases

Database Migrations 

# Create migration command
tapit create command name=db-migrate 'rails db:migrate' description='Run database migrations'

# Add as pre-deploy step
tapit create predeploy_step name=db-migrate

Application Smoke Tests 

# Create smoke test command
tapit create command name=smoke-test 'rails runner "AppHealthCheck.verify!"' description='Verify app starts correctly'

# Add as pre-deploy step
tapit create predeploy_step name=smoke-test

Asset Compilation or Cache Warming 

# Create cache warming command
tapit create command name=warm-cache 'rails runner "CacheWarmer.run"' description='Pre-warm application caches'

# Add as pre-deploy step
tapit create predeploy_step name=warm-cache

Multiple Pre-deploy Steps 

# Create commands
tapit create command name=db-migrate 'rails db:migrate'
tapit create command name=db-seed-config 'rails runner "ConfigSeeder.run"'
tapit create command name=smoke-test 'rails runner "SmokeTest.run"'

# Add as pre-deploy steps (they run in the order added, reorder in UI if needed)
tapit create predeploy_step name=db-migrate
tapit create predeploy_step name=db-seed-config
tapit create predeploy_step name=smoke-test

Best Practices

  1. Keep Steps Fast: While steps can take as long as needed, faster steps mean faster deployments
  2. Idempotent Operations: Design commands to be safely re-runnable in case of deployment retries
  3. Meaningful Names: Use descriptive command names that indicate what the step does
  4. Order Matters: Place critical operations (like migrations) before validation steps (like smoke tests)
  5. Test Commands First: Run commands manually with tapit create task 'command' before adding them as pre-deploy steps

Troubleshooting

Pre-deploy Step Fails

If a pre-deploy step fails:

  1. The deployment is aborted and no containers are updated
  2. Check the task logs for the failed step to identify the issue
  3. Fix the underlying problem
  4. Retry the deployment
# Check recent task logs
tapit show logs

# List recent tasks to find the failed pre-deploy task
tapit list tasks

Step Order Issues

If steps need to run in a different order:

  1. Use the web interface to drag and drop steps into the correct order
  2. Or delete and re-add steps in the desired order via CLI
DeploymentsReleases