Pre-flight checks for Railway deployments to catch failures BEFORE deploying. Use when about to deploy, running verify-* commands, or debugging Railway issues.
Pre-flight checks for Railway deployments and verify-* commands. Catches common configuration issues before they cause deployment failures.
Run these checks BEFORE deploying or running verify-* commands (like verify-pipeline, verify-deployment, etc.) to catch issues early.
Verify Railway CLI is authenticated and has an active context:
# Check for Railway environment or token
if [[ -z "${RAILWAY_ENVIRONMENT:-}" && -z "${RAILWAY_API_TOKEN:-}" && -z "${RAILWAY_TOKEN:-}" ]]; then
echo "ERROR: No Railway context found."
echo " Set RAILWAY_ENVIRONMENT or the canonical automation token RAILWAY_API_TOKEN, or run: railway login"
exit 1
fi
# Verify CLI can connect
railway status 2>/dev/null || {
echo "WARNING: Railway CLI not connected. Run: railway login"
}
What it checks:
RAILWAY_ENVIRONMENT - Environment variable set by RailwayRAILWAY_API_TOKENRAILWAY_TOKEN - compatibility fallback onlyQuick Fix:
railway login
# Interactive context:
railway shell
# Worktree/automation-safe context (no local link required):
railway run -p <project-id> -e dev -s backend -- env | grep RAILWAY_SERVICE
# Or for CI/automation, load RAILWAY_API_TOKEN through the agent-safe cache:
~/agent-skills/scripts/dx-load-railway-auth.sh -- railway whoami
For DB-heavy host workflows, do not hand-roll railway run ... psql "$DATABASE_URL" if the service injects internal-only hosts. Prefer:
~/agent-skills/scripts/dx-load-railway-auth.sh -- \
~/agent-skills/scripts/dx-railway-postgres.sh \
--project-id <project-id> \
--env dev \
query --sql 'SELECT 1'
Verify required service URL variables are configured:
# Check for service URL variables
MISSING_URLS=()
[[ -z "${RAILWAY_SERVICE_FRONTEND_URL:-}" ]] && MISSING_URLS+=("RAILWAY_SERVICE_FRONTEND_URL")
[[ -z "${RAILWAY_SERVICE_BACKEND_URL:-}" ]] && MISSING_URLS+=("RAILWAY_SERVICE_BACKEND_URL")
if [[ ${#MISSING_URLS[@]} -gt 0 ]]; then
echo "ERROR: Missing service URL variables: ${MISSING_URLS[*]}"
echo " These are required for verify-* commands to work."
echo ""
echo "Quick Fix:"
echo " railway run -p <project-id> -e dev -s backend -- env | grep RAILWAY_SERVICE"
exit 1
fi
What it checks:
RAILWAY_SERVICE_FRONTEND_URL - Frontend service public URLRAILWAY_SERVICE_BACKEND_URL - Backend service public URLQuick Fix:
# Check what URL variables are available
railway run -p <project-id> -e dev -s backend -- env | grep RAILWAY_SERVICE
# Or set manually from Railway dashboard:
# Project > Service > Settings > Domains > Copy URL
railway variables set RAILWAY_SERVICE_FRONTEND_URL="https://your-app.up.railway.app"
railway variables set RAILWAY_SERVICE_BACKEND_URL="https://your-api.up.railway.app"
Verify test authentication bypass secret is configured (for E2E tests):
# Check for auth bypass secret
if [[ -z "${TEST_AUTH_BYPASS_SECRET:-}" ]]; then
echo "WARNING: TEST_AUTH_BYPASS_SECRET not set."
echo " E2E tests requiring auth bypass may fail."
echo ""
echo "Quick Fix:"
echo " railway variables set TEST_AUTH_BYPASS_SECRET='<from-1password>'"
fi
What it checks:
TEST_AUTH_BYPASS_SECRET - Secret for bypassing auth in E2E/integration testsQuick Fix:
# TEST_AUTH_BYPASS_SECRET is a Railway env var
railway run -p <project-id> -e dev -s backend -- env | grep TEST_AUTH_BYPASS_SECRET
# Or verify it's set in Railway (if not, check Railway dashboard)
railway variables | grep TEST_AUTH_BYPASS_SECRET
All pre-flight failures can be diagnosed/fixed via Railway context:
# Open interactive Railway shell
railway shell
# OR run targeted checks from worktree
railway run -p <project-id> -e dev -s backend -- env | grep -E "RAILWAY_SERVICE|TEST_AUTH"
# Inside shell, check environment
env | grep RAILWAY
env | grep TEST_AUTH
# Set missing variables
variable set KEY=value
Run all checks at once:
#!/bin/bash
# railway-preflight.sh
ERRORS=0
# 1. Railway Context
if [[ -z "${RAILWAY_ENVIRONMENT:-}" && -z "${RAILWAY_API_TOKEN:-}" && -z "${RAILWAY_TOKEN:-}" ]]; then
echo "[FAIL] No Railway context (RAILWAY_ENVIRONMENT or Railway automation token)"
ERRORS=$((ERRORS + 1))
else
echo "[OK] Railway context found"
fi
# 2. URL Variables
[[ -n "${RAILWAY_SERVICE_FRONTEND_URL:-}" ]] && echo "[OK] RAILWAY_SERVICE_FRONTEND_URL set" || { echo "[FAIL] Missing RAILWAY_SERVICE_FRONTEND_URL"; ERRORS=$((ERRORS + 1)); }
[[ -n "${RAILWAY_SERVICE_BACKEND_URL:-}" ]] && echo "[OK] RAILWAY_SERVICE_BACKEND_URL set" || { echo "[FAIL] Missing RAILWAY_SERVICE_BACKEND_URL"; ERRORS=$((ERRORS + 1)); }
# 3. Auth Secret
[[ -n "${TEST_AUTH_BYPASS_SECRET:-}" ]] && echo "[OK] TEST_AUTH_BYPASS_SECRET set" || { echo "[WARN] TEST_AUTH_BYPASS_SECRET not set (E2E tests may fail)"; }
# Summary
echo ""
if [[ $ERRORS -gt 0 ]]; then
echo "Pre-flight FAILED with $ERRORS error(s)"
echo "Run 'railway shell' OR 'railway run -p <id> -e <env> -s <svc> -- <cmd>' to diagnose and fix"
exit 1
else
echo "Pre-flight PASSED - ready to deploy"
fi