Deployment Workflow

Document: 27-deployment-workflow.md
Version: 1.0.0

Purpose

This document defines the standard deployment workflow used across all Rundown projects.

A deployment is the controlled process of promoting tested application code into a production environment. Standardizing this workflow reduces operational risk, improves reliability, and ensures every deployment follows the same quality standards.

Deployment Philosophy

Deployments should be:

Repeatable
Predictable
Reversible
Observable
Automated

A deployment should never rely on undocumented manual steps.

The deployment process itself should be version-controlled alongside the application.

Deployment Pipeline

Every deployment follows the same progression:

Development

↓

Code Review

↓

Merge to Main

↓

Automatic Build

↓

Deploy to Staging

↓

Validation

↓

Deploy to Production

No deployment should bypass this workflow except during documented emergency procedures.

Deployment Requirements

Before deployment:

All tests must pass.
Code review must be complete.
Documentation must be updated.
Database migrations must be reviewed.
Environment variables must be verified.
Required approvals must be obtained.

Deployment is the final step—not the testing phase.

Staging Validation

Every production deployment should first be validated in staging.

Validation includes:

Functional testing
CMS verification
Responsive behaviour
Forms
Authentication
Integrations
Performance review

Production should not become the testing environment.

Database Migrations

Schema migrations should:

Be version controlled.
Execute automatically where appropriate.
Be reviewed before deployment.
Remain backward compatible whenever practical.

Manual production database modifications are prohibited.

Rollback Strategy

Every deployment should have a defined rollback path.

Rollback may include:

Previous application image
Previous release
Database rollback (when supported)
Infrastructure restoration

Rollback procedures should be documented before deployment.

Deployment Logging

Every deployment should record:

Version
Date and time
Environment
Deployed by
Deployment status
Relevant notes

Deployment history should be available for future auditing and troubleshooting.

Zero-Downtime Deployments

Where practical, deployments should minimize service interruption.

Strategies may include:

Container replacement
Health checks
Rolling updates
Graceful restarts

User impact should be minimized during routine deployments.

Failure Handling

If deployment validation fails:

Stop the deployment.
Investigate the issue.
Roll back if necessary.
Document the incident.
Correct the underlying cause before redeployment.

Deployment failures should improve future deployment processes.

Production Verification

Immediately after deployment, verify:

Application availability
Core user journeys
CMS functionality
Forms
Email delivery
Monitoring status
Error logs

Production verification confirms successful release.

Versioning

Every deployment should correspond to a documented application version.

Version numbers should remain synchronized with:

Git tags
Changelog
Deployment history

Engineering Decision

Standard Deployment Workflow

Status: Accepted

Decision

All Rundown projects follow a single standardized deployment workflow from development through production.

Reasoning

A consistent deployment process:

Reduces operational errors.
Simplifies onboarding.
Improves deployment reliability.
Supports predictable releases.
Enables continuous improvement.

Deployment Checklist

Before deploying to production, verify:

Code reviewed.
Tests passed.
Documentation updated.
Environment variables verified.
Database migrations reviewed.
Staging validated.
Rollback plan available.
Monitoring ready.

Summary

Deployment is the controlled promotion of tested software into production.

By following a standardized deployment workflow, Rundown minimizes operational risk while delivering reliable, predictable, and repeatable releases.

ADR-003: Documentation Information Architecture