Skip to content

Change Management Process

Purpose. Ensures changes to Soon's platform and infrastructure are reviewed, tested and reversible, so that changes do not introduce security weaknesses or unplanned downtime (ISO/IEC 27001 A.8.32, A.8.19, A.5.22).

1. Scope

All changes to Soon's production systems: application code, infrastructure and configuration (AWS eu-west-1, Netlify), CI/CD pipelines, and security-relevant settings in third-party services (GitHub, Stripe, Intercom, Sentry, PostHog). ISMS documentation follows the pull-request workflow of the ISMS repository itself.

2. Principles — how change is actually controlled here

Soon ships continuously. A process that required a human to inspect every change would not survive contact with that reality: it would either be ignored, or become a rubber stamp that provides assurance in name only. Neither is a control.

So the control is the pipeline, not the person. This is the model used by high-deployment-frequency engineering organisations, and it rests on four ideas:

  1. Automation gates every change. Machines check every single change, without fatigue or exceptions. This is stronger than human review precisely because it cannot be skipped when someone is in a hurry.
  2. Human attention is spent where risk is. Reviewing a copy change costs the same attention as reviewing an authentication change, but is worth far less. Review is therefore targeted at code that can actually hurt customers.
  3. Small changes, frequently. A large batched release is harder to review, riskier to deploy and slower to diagnose. Frequent small changes are safer, not riskier.
  4. Recovery over prevention. No process catches everything. What matters as much as prevention is detecting a bad change quickly and reversing it quickly.

On the standards. Neither SOC 2 (CC8.1) nor ISO 27001 (A.8.32) requires human review of every change. They require that changes are authorised, tested, traceable and reversible. Automated, non-bypassable gates satisfy that, and are easier to evidence than a signature.

3. The change path

3.1 Every change, without exception

  1. Made on a branch and proposed as a GitHub pull request. Direct pushes to the default branch are blocked by branch protection, so this cannot be bypassed.
  2. Must pass the automated gate before merge: build, unit and integration tests, authentication and authorisation tests, linting, TypeScript and schema (Prisma) validation, OpenAPI contract checks, dependency and container updates, secret scanning, and AI-assisted code review.
  3. The PR states what changes and why. Security-relevant impact (authentication, authorisation, data handling, dependencies, exposure of customer data) is called out.
  4. Reaches production only through the CI/CD pipeline from the merged default branch — never by manual, untracked deployment.

3.2 Where a human review is required

Human review is required for changes touching:

  • Authentication, authorisation, session or token handling
  • Customer data access paths, including API scopes and tenant isolation
  • Payment and billing logic
  • Infrastructure, network and IAM configuration
  • Database migrations that are destructive or not reversible
  • Cryptography and secrets handling

Everywhere else — product changes that do not touch the above, internal tooling, documentation, non-production configuration — the automated gate is the approval, and the author may merge once it passes.

TODO(owner: Thomas): encode this in CODEOWNERS so the requirement is enforced by GitHub rather than remembered by people. That single file turns this section from a statement of intent into a control an auditor can test.

3.3 Deploy small and often

  • Changes are kept small and merged frequently; long-lived branches are avoided.
  • Where a change is risky or incomplete, it ships disabled behind a feature flag and is enabled separately, so deployment and release are decoupled. TODO(owner: Thomas): confirm the feature-flag mechanism in use.
  • Frontend deploys are atomic with immediate rollback (Netlify); backend deploys roll out through ECS with health checks.

3.4 Detect and recover

Because not every defect is preventable, recovery is treated as a first-class control:

  • Monitoring: Sentry for application errors with release correlation, CloudWatch metrics and alarms, GuardDuty for security anomalies. A deploy that raises the error rate is visible within minutes.
  • Rollback: revert the commit and redeploy, or redeploy the previous release (Netlify keeps prior deploys; ECS retains the previous task definition). Every change must be reversible, and database migrations must either have a rollback path or state explicitly in the PR that the risk is accepted.
  • Fix forward is a legitimate choice when it is faster and safer than reverting; the decision is recorded in the incident.

3.5 Emergency changes

When a production incident requires an immediate fix, restoring service takes precedence: the fix may be merged and deployed without a prior approving review. The automated gate still applies. Every emergency change is reviewed retrospectively at the next weekly ISMS meeting (Thursdays 13:00 CEST) — confirm the fix is sound, record why the normal path was bypassed, and identify follow-up work. That retrospective is what makes this a controlled exception rather than a gap, so it must actually happen and be minuted.

3.6 Infrastructure changes

Infrastructure follows the same PR flow where it is managed as code (OpenTofu/Terraform). Manual console changes to production are limited to MFA-secured accounts and are captured by CloudTrail. TODO(owner: Melvin): confirm which parts of the estate are codified and which are still changed by hand.

3.7 Upstream changes from providers

Soon depends on AWS and a small set of SaaS providers. Deprecations, breaking changes and security advisories are monitored through Dependabot and Aikido alerts, provider status pages and email notifications, and material items are raised at the weekly ISMS meeting. TODO(owner: Thomas): confirm who watches provider notifications.

3.8 Customer-affecting changes

Changes causing customer-visible downtime or behaviour change are announced in advance by email and via the status page at https://status.soon.works/.

4. How we know this is working

A fast process is defensible when it is measured. Soon tracks four industry-standard delivery metrics, reviewed at the management review:

Metric What it shows Target
Deployment frequency Changes are small and continuous Maintain or increase
Lead time for change Speed from commit to production Maintain or reduce
Change failure rate Share of deploys causing an incident or rollback < 15%
Time to restore How quickly a bad change is reversed < 1 hour

The last two are the ones that matter for assurance: they demonstrate that the process catches and corrects failures quickly. TODO(owner: Thomas): confirm where these are measured from (GitHub Actions and Netlify deploy history, incident records in Linear).

5. Roles & responsibilities

  • Author (any engineer) — proposes the change, ensures tests and rollback are considered, and requests review where §3.2 requires it.
  • Reviewer — approves only when the change is understood, tested and secure. Soon has no Change Advisory Board; the PR is the approval gate.
  • Security responsible (Olaf Jacobson) — owns this process, reviews emergency-change retrospectives, and is consulted on security-sensitive changes.
  • Platform (Thomas Picauly) — maintains branch protection, CODEOWNERS and the automated gate, so the control cannot silently degrade.

Change log

Version Date Author Comments
0.1 2023-12-11 Alessandro Cardinali First draft document
0.2 2026-07-18 Andrea Cardinali Rewritten lean and Soon-specific — GitHub PR + CI/CD instead of ITIL/CAB
0.3 2026-08-13 ISMS Rewritten around continuous delivery: the automated gate is the primary control on every change; human review is targeted by risk (auth, customer data, payments, infrastructure, destructive migrations, crypto) and to be enforced via CODEOWNERS; adds small-and-frequent deploys, feature flags, detect-and-recover, and DORA delivery metrics with a change-failure-rate and time-to-restore target as the evidence that a fast process is a controlled one.