This is the canonical workflow for publishing validated content through test and production environments with comprehensive preflight checks.
Overview The release process workflow ensures safe publication by:
Running preflight validation before each environment
Publishing assets, catalog, and content in correct order
Deploying the site with production safeguards
Maintaining environment consistency
Production-critical workflow This workflow deploys live content. Always run preflight checks and validate in test before publishing to production.
Workflow Steps
Run test environment preflight
Execute preflight validation for the test environment: dex release preflight --env test
Preflight checks:
Entry runtime audit for all active entries
Protected asset coverage for active catalog lookups
Catalog validation (manifest integrity, linkage)
Generated HTML secure checks
If preflight fails, stop immediately . Do not proceed to publish until all errors are resolved.
Publish to test environment
After successful preflight, publish all content to test: dex release publish --env test
This executes in order:
Assets publish
Catalog publish
Local snapshot sync (non-dry-run)
Verify the test environment after publish to ensure content is correct.
Run production environment preflight
Execute preflight validation for production: dex release preflight --env prod
Production preflight runs the same checks as test, validating against production environment state. Never skip production preflight. Do not use --no-preflight flag except in emergency situations with explicit approval.
Publish to production environment
After successful production preflight, publish: dex release publish --env prod
Production publish executes the same sequence as test but targets production infrastructure. Ensure you have:
Verified test environment content
Reviewed all diffs between local and production
Obtained necessary approvals for production changes
Deploy the site
Deploy the site with production preflight validation: dex deploy --preflight-env prod
This command:
Runs preflight validation (unless --no-preflight is used)
Pushes to git remote with upstream tracking
Triggers site deployment pipeline
Production deployment policy: Always use --preflight-env prod for production deployments. Never use --no-preflight except in emergency situations.
Stop Conditions Halt the workflow immediately if any of these occur:
Any preflight failure in test or production
Missing active lookup coverage in assets
Generated HTML secure check failure
Unexpected or large diffs between environments
Authentication/token errors during publish
Verification Commands Pre-publish verification # Run preflight for both environments dex release preflight --env test dex release preflight --env prod # Diff before publish to review changes dex assets diff --env test dex catalog diff --env test dex home diff --env test
Dry-run testing # Test publish without making changes dex release publish --env test --dry-run dex release publish --env prod --dry-run
Post-publish verification # Pull current state from environments dex catalog pull --env test dex home pull --env test # Verify production state matches expectations dex catalog diff --env prod dex home diff --env prod
Advanced Options Override API endpoints and tokens For non-standard deployments or testing:
# Override base API endpoint dex release publish --env test --api-base https://custom.api.example.com # Override specific service endpoints dex release publish --env prod \ --assets-api-base https://assets.example.com \ --catalog-api-base https://catalog.example.com # Override authentication tokens (use environment variables instead when possible) dex release publish --env test --token $CUSTOM_TOKEN
Store admin tokens in environment variables, never in command history or scripts. See Security Configuration for token management. High-Risk Flags Policy Emergency-only flags:
dex deploy --no-preflight - Bypasses all preflight validationdex release publish --no-preflight - Publishes without safety checks These flags should only be used:
During incident response with explicit approval
When preflight system is broken but content is verified
With full understanding of risks and manual verification
Next Steps After successful release:
Entry Validation Validate and prepare new entries for next release
Notes Editorial Publish editorial notes and updates
Troubleshooting Admin token/environment mismatch Symptom: Publish/diff auth failures against Worker admin endpoints.Fix:
Confirm correct environment (test vs prod)
Verify token variable is exported in shell:
echo $DEX_CATALOG_ADMIN_TOKEN_PROD echo $DEX_ASSETS_ADMIN_TOKEN_PROD
Confirm token secret exists in Worker environment (check dex-api Wrangler configuration)
Re-export tokens if needed and retry
Preflight fails on entry audit Symptom: Preflight reports entry runtime validation failures.Fix:
Identify failing entries:
Fix individual entries:
dex update # Select failing entry
Re-run preflight after corrections