Version 1.1

Status Active

Owner Head of Engineering

Last Updated 2026-06-23

SOP: Deployment Process

1. Purpose

The purpose of this SOP is to define how application changes are deployed to development, staging, and production environments.

This SOP explains who may deploy, what may be deployed, when deployment is allowed, how deployments are approved, and how deployments should be documented.

The goal is to ensure that deployments are:

controlled,
traceable to a specific version,
approved when required,
verified after completion,
and connected to the Ticket Management, Pull Request, Git Flow, and QA processes.

2. Scope

This SOP applies to all deployments performed through GitHub Actions, CI/CD pipelines, or any other approved deployment mechanism.

It applies to:

Frontend frontend deployments, PR previews, staging deployments, and production deployments,
Backend backend service deployments, API deployments, and production service changes,
DevOps infrastructure, CI/CD, environment, and operational deployments,
QA staging deployments used for formal QA verification,
Engineering shared engineering systems, scripts, and deployment-related changes.

This SOP does not replace the Ticket Management SOP, Pull Request SOP, Git Flow SOP, or QA SOP. It defines the deployment rules and handoff points that connect those procedures.

3. Core Rule

Mandatory Every deployment must be traceable to a specific branch, commit SHA, build, deployment ID, or future release tag.

The default deployment flow is:

Pull Request → development → staging → main → production

Changes merged into development are automatically deployed to the development environment. Staging and production deployments are manually triggered and approval-gated when required.

Production deployment must happen from main. Deploying directly to production from development is not allowed during normal operation.

4. Rule Strictness

Level	Meaning
Mandatory	Must be followed unless there is an approved and documented exception.
Default	Should normally be followed, but exceptions are allowed when justified.
Recommended	Encouraged, but not strictly required in every case.

5. Definitions

Term	Meaning
Deployment	The process of publishing a selected application version to a target environment.
Deployable Version	A specific commit SHA, build, deployment ID, or future release tag that can be deployed.
Commit SHA	A Git commit identifier used to identify the exact version being deployed.
PR Preview	A temporary or PR-specific frontend deployment created for early review or informal validation.
Development Environment	The environment automatically deployed from `development` after a PR is merged.
Staging Environment	The environment used for formal QA verification and production readiness validation.
Production Environment	The live environment used by real users.
Approval Gate	A manual approval step required before a deployment pipeline is allowed to continue.
Deployment Owner	The person responsible for triggering, monitoring, and verifying a deployment.
Rollback / Recovery	The process of restoring service by deploying a previous known-good version when needed.
Post-Deployment Verification	Checks performed after deployment to confirm that the environment is healthy and expected behavior works.

6. Roles and Responsibilities

Role	Responsibilities
PR Author	Ensures the PR is merged into `development`, confirms the automatic development deployment when applicable, and provides the merge commit SHA or testable version for QA.
Ticket Owner	Keeps the related ticket updated, provides context for QA or deployment, and ensures deployment-related information is documented when needed.
QA	May trigger or request staging deployments, verifies selected versions on staging, documents QA results, and approves or rejects work for production readiness when responsible.
DevOps	Supports deployment pipelines, environment configuration, approval gates, rollback/recovery, deployment troubleshooting, and production deployments when authorized.
Responsible Individual / Team	May deploy selected versions to staging or production when authorized and responsible for that project or environment.
Deployment Owner	Triggers the deployment, monitors the pipeline, confirms the deployed version, communicates issues, and ensures post-deployment verification is completed.
Head of Engineering	Owns the deployment process, approves exceptions, resolves escalations, and confirms release-blocking decisions when needed.
Authorized Approver	A person or team with the required permission to approve gated staging or production deployments.

7. Deployment Environments

7.1 PR preview environment

Recommended Frontend projects may automatically deploy a PR preview on every PR commit.

PR previews are used for early review, visual inspection, informal validation, and feedback before merge.

PR previews do not replace formal QA verification on staging unless an exception is approved.

Backend preview environments are not required by this SOP. Backend changes should be validated through CI, the development environment, and formal staging verification.

7.2 Development environment

Mandatory The development environment is automatically deployed from development after a PR is merged.

The development environment is used for integration checks, early validation, internal review, and debugging after changes enter development.

The development environment is not the formal QA approval environment by default. Formal QA verification should happen on staging.

7.3 Staging environment

Mandatory The staging environment is used for formal QA verification and production readiness validation.

Staging deployments are manually triggered using a selected version from development, usually the merge commit SHA provided in the related ticket or QA handoff notes.

Staging deployment may require approval from the responsible reviewer, team, or individual before the pipeline starts.

7.4 Production environment

Mandatory The production environment is the live environment used by real users.

Production deployment must happen from main.

Production deployments are manually triggered and must pass the required approval gate before the pipeline starts.

Production deployment should happen only after QA or the responsible individual/team confirms that the relevant changes are acceptable for production.

8. Deployment Sources and Versioning

8.1 Source branches

Environment	Source	Trigger	Purpose
PR Preview	PR branch	Automatic on PR commit	Early review and informal validation
Development	`development`	Automatic after PR merge	Integration and internal validation
Staging	Selected version from `development`	Manual GitHub Actions run	Formal QA verification
Production	Selected version from `main`	Manual GitHub Actions run	Live production release

8.2 Version identifiers

Mandatory Staging and production deployments must identify the version being deployed.

Accepted version identifiers include:

commit SHA,
merge commit SHA,
build number,
deployment ID,
or future release tag.

Since release tags are not currently used, the commit SHA or merge commit SHA should be used as the primary deployment identifier.

8.3 Historical deployments

Default Authorized users may deploy the latest version or a historical version to staging or production when needed.

Historical deployments may be used for:

rollback or recovery,
testing a specific previous version,
reproducing a reported issue,
validating a previous release candidate,
or restoring a known-good state.

Historical deployments should be clearly documented with the deployed version and reason.

9. Development Deployment

9.1 Automatic deployment after merge

Mandatory Every PR merged into development should automatically deploy to the development environment.

The PR author or responsible team should confirm that the deployment completed successfully when the change is relevant to active work or QA handoff.

9.2 Development deployment failure

If the automatic development deployment fails, the PR author, ticket owner, DevOps, or responsible team should investigate.

The related ticket should not be moved to Ready for Test until the work is available as a testable version or the deployment issue is otherwise resolved.

9.3 Development environment usage

Development may be used for integration checks, internal validation, informal QA, debugging, and confirming that merged work is available.

Development checks do not replace formal QA verification on staging unless an exception is approved.

10. Staging Deployment

10.1 When staging deployment is allowed

Mandatory Staging deployment is allowed when there is a selected version from development that needs QA verification or production readiness validation.

Staging should normally be used for:

formal QA verification,
release candidate validation,
cross-team validation,
regression testing,
or verifying a specific version before production promotion.

10.2 Who may deploy to staging

Default QA, DevOps, or an authorized responsible individual/team may manually deploy to staging.

The staging deployment pipeline may require approval before the deployment starts.

The person triggering the deployment is responsible for selecting the correct version and confirming the deployment result.

10.3 Staging deployment requirements

Before deploying to staging, the deployment owner should confirm:

the selected version exists in development,
the selected version or SHA is known,
the reason for staging deployment is clear,
the related ticket, QA request, or validation purpose is clear,
and the deployment approval gate is completed when required.

10.4 Staging deployment documentation

Default For QA-related staging deployments, the tested version or SHA should be documented in the related ticket or QA result.

The full deployment documentation process may be expanded later. For now, the minimum required traceability is:

the deployed version or SHA,
the related ticket or purpose,
and the QA result or deployment outcome when applicable.

11. Production Readiness

11.1 Production readiness requirement

Mandatory Production deployment requires QA approval or approval from the responsible individual/team.

Before code is promoted to production, the relevant changes should be verified on staging or approved through an accepted exception.

11.2 Production readiness checklist

Before opening or merging a PR into main, confirm that:

the relevant changes are merged into development,
the selected version has been tested or approved,
QA approval or responsible team approval exists,
known risks are documented,
the production deployment owner is clear,
and rollback or recovery approach is understood when applicable.

12. Promotion to main

12.1 PR from development into main

Mandatory Production-ready changes should be promoted by creating a PR from development into main.

This PR represents the code being approved for production deployment.

The PR into main should describe:

what is being promoted,
related tickets or PRs,
QA or verification status,
known risks,
deployment notes,
and rollback or recovery notes when applicable.

12.2 Merging into main

A PR into main may be merged only when:

production readiness is confirmed,
required approvals exist,
required checks pass,
there are no unresolved blocking concerns,
and the production deployment owner is clear.

Merging into main does not automatically mean production is deployed unless the repository pipeline is explicitly configured that way. In this workflow, production deployment is manually triggered.

13. Production Deployment

13.1 Who may deploy to production

Mandatory Production deployment may be performed only by DevOps, Head of Engineering, or an explicitly authorized responsible person/team.

Production deployment must pass the required approval gate before the pipeline starts.

13.2 Production deployment requirements

Before deploying to production, the deployment owner must confirm:

the selected version exists in main,
the selected version or SHA is known,
QA approval or responsible team approval exists,
the production deployment approval gate is completed,
known risks are documented,
and rollback or recovery approach is understood when applicable.

13.3 Triggering production deployment

Production deployment should be manually triggered through the approved deployment pipeline.

The deployment owner is responsible for selecting the correct version, monitoring the pipeline, and communicating success or failure.

13.4 Production deployment documentation

Default Production deployments should be documented in the production PR, deployment run, release note, ticket, or appropriate communication channel.

Production deployment documentation should include:

deployed version or SHA,
deployment owner,
deployment time,
target environment,
related PR or ticket,
deployment result,
post-deployment verification result,
and rollback or follow-up notes when applicable.

14. Post-Deployment Verification

14.1 Staging verification

After staging deployment, QA or the responsible individual/team should verify the selected version according to the QA SOP.

The tested version or SHA should be documented in the QA result.

14.2 Production smoke verification

Mandatory Production deployment should be followed by basic post-deployment verification.

Production smoke verification may include:

confirming the application loads,
checking critical user flows,
checking API health endpoints when applicable,
checking logs for obvious new critical errors,
checking monitoring or alerts when available,
and confirming the deployed version is correct.

14.3 Verification failure

If post-deployment verification fails, the deployment owner should communicate the issue immediately and coordinate with the responsible team.

The team should decide whether to fix forward, redeploy a previous known-good version, or take another recovery action.

15. Rollback and Recovery

15.1 Recovery approach

Default Before production deployment, the deployment owner should know which previous version can be redeployed if needed.

Rollback or recovery is currently performed by manually triggering the deployment pipeline with a previous known-good SHA or version.

The rollback or recovery deployment remains approval-gated in the same way as normal production deployment unless an emergency exception is approved.

15.2 When rollback or recovery may be needed

Rollback or recovery may be needed when:

production smoke verification fails,
a critical bug is discovered after deployment,
monitoring or logs show serious new errors,
users are blocked from critical functionality,
or the deployment causes unacceptable operational risk.

15.3 Rollback documentation

If rollback or recovery is performed, the deployment owner should document:

reason for rollback or recovery,
previous deployed version,
replacement deployed version,
person who triggered the deployment,
approval or exception used,
verification result,
and follow-up actions.

16. Deployment Documentation

16.1 Minimum documentation for staging

For staging deployments used by QA, the minimum required documentation is:

tested version or SHA,
related ticket or QA request,
QA result,
and any blocking deployment issue.

16.2 Minimum documentation for production

For production deployments, the minimum recommended documentation is:

deployed version or SHA,
deployment owner,
deployment time,
related PR or ticket,
deployment result,
post-deployment verification result,
and rollback or follow-up notes when applicable.

16.3 Where deployment information may be documented

Deployment information may be documented in:

the related ticket,
the QA result,
the production PR,
the GitHub Actions deployment run,
a release note,
or an appropriate communication channel.

The documentation location may be standardized further in a future version of this SOP.

17. Procedure

17.1 PR preview deployment

Developer opens or updates a PR.
Frontend preview deployment runs automatically when configured.
Pipeline posts or exposes the preview URL.
Developer, reviewer, QA, or responsible individual may use the preview for early validation.
Preview feedback is handled through the PR or related ticket.

17.2 Development deployment

PR is approved according to the Pull Request SOP.
PR is merged into development.
Pipeline automatically deploys the latest development version to the development environment.
PR author or responsible team confirms deployment success when relevant.
PR author or ticket owner updates the related ticket and provides the merge commit SHA when QA is needed.

17.3 Staging deployment

QA or responsible individual/team selects the version or SHA from development.
QA or responsible individual/team manually triggers the staging deployment pipeline.
Required deployment approval is completed.
Pipeline deploys the selected version to staging.
Deployment owner confirms staging deployment result.
QA verifies the selected version according to the QA SOP.
Tested version or SHA is documented in the ticket or QA result.

17.4 Production promotion

QA or responsible individual/team confirms production readiness.
Responsible individual/team creates a PR from development into main.
PR describes included changes, related tickets, QA status, risks, and deployment notes.
PR is reviewed and approved.
PR is merged into main.

17.5 Production deployment

Deployment owner selects the version or SHA from main.
Deployment owner manually triggers the production deployment pipeline.
Required production deployment approval is completed.
Pipeline deploys the selected version to production.
Deployment owner monitors the deployment result.
Deployment owner or responsible team performs post-deployment verification.
Deployment result and verification result are documented.

17.6 Rollback or recovery deployment

Responsible individual/team identifies the previous known-good SHA or version.
Authorized deployment owner manually triggers the deployment pipeline with that version.
Required approval gate is completed unless an emergency exception is approved.
Pipeline deploys the selected previous version.
Deployment owner verifies system recovery.
Rollback reason, version, and verification result are documented.
Follow-up issue or cleanup task is created when needed.

18. Exceptions

18.1 Urgent production incidents

Urgent production incidents may require an accelerated deployment or recovery process.

Even in urgent situations:

a ticket must exist or be created as soon as possible,
the deployed version must be documented,
the reason for the exception must be documented,
accepted risks must be documented,
and follow-up cleanup must be created when needed.

the correct version was selected,
required approvals were completed,
the deployment pipeline completed successfully,
the deployed version or SHA is known,
the deployment result is documented when required,
post-deployment verification is completed when required,
any failure, rollback, or recovery action is documented,
and related tickets, PRs, or QA results are updated when applicable.

20. Short Checklist

20.1 Before staging deployment

Selected version exists in development.
Version or SHA is known.
Related ticket or QA request is clear.
Deployment owner is clear.
Approval gate is completed when required.

20.2 After staging deployment

Deployment completed successfully.
Tested version or SHA is documented.
QA verifies the change on staging.
QA result is documented in the ticket.
Failures or blockers are communicated.

20.3 Before production promotion

Relevant changes are merged into development.
QA or responsible team approval exists.
Known risks are documented.
Production deployment owner is clear.
Rollback or recovery approach is understood when applicable.
PR from development into main is created.

20.4 Before production deployment

PR into main is merged.
Selected version exists in main.
Version or SHA is known.
Production approval gate is completed.
Deployment owner is available.
Post-deployment verification plan is clear.

20.5 After production deployment

Deployment completed successfully.
Application or service health is checked.
Critical flows are smoke-tested when applicable.
Logs, alerts, or monitoring are checked when available.
Deployment result is documented.
Rollback or follow-up is started if needed.

20.6 Before rollback or recovery

Issue or incident is understood enough to act.
Previous known-good version or SHA is identified.
Deployment owner is clear.
Approval gate is completed unless an emergency exception is approved.
Communication and follow-up plan are clear.

21. Workflow Diagram

21.1 Standard deployment workflow

flowchart TD
  A[Developer Opens PR] --> B{Frontend PR Preview Enabled?}
  B -- Yes --> C[Automatic PR Preview Deployment]
  B -- No --> D[PR Review]
  C --> D
  D --> E{Approved and Checks Passing?}
  E -- No --> F[Author Updates PR]
  F --> D
  E -- Yes --> G[Merge PR into development]
  G --> H[Automatic Development Deployment]
  H --> I[Author Provides Merge Commit SHA]
  I --> J[Ticket Ready for QA]
  J --> K[QA Selects SHA from development]
  K --> L[Manual Staging Deployment]
  L --> M{Staging Approval Gate Passed?}
  M -- No --> N[Document Blocker]
  M -- Yes --> O[Deploy Selected Version to Staging]
  O --> P[QA Verifies on Staging]
  P --> Q{Approved for Production?}
  Q -- No --> R[Return Ticket to Reopened or Needs Info]
  Q -- Yes --> S[Create PR development to main]
  S --> T[Review Production PR]
  T --> U{Approved and Checks Passing?}
  U -- No --> V[Resolve Blocking Concerns]
  V --> T
  U -- Yes --> W[Merge into main]
  W --> X[Manual Production Deployment]
  X --> Y{Production Approval Gate Passed?}
  Y -- No --> Z[Document Blocker]
  Y -- Yes --> AA[Deploy Selected Version to Production]
  AA --> AB[Post-Deployment Verification]
  AB --> AC[Deployment Complete]

21.2 Rollback and recovery workflow

flowchart TD
  A[Production Issue Detected] --> B[Assess Severity]
  B --> C{Rollback or Recovery Needed?}
  C -- No --> D[Fix Forward or Monitor]
  C -- Yes --> E[Identify Previous Known-Good SHA]
  E --> F[Authorized Owner Triggers Deployment Pipeline]
  F --> G{Approval Gate Passed?}
  G -- No --> H[Document Blocker or Approve Exception]
  H --> F
  G -- Yes --> I[Deploy Previous Version]
  I --> J[Verify System Recovery]
  J --> K{Recovered?}
  K -- Yes --> L[Document Result and Follow-Up]
  K -- No --> M[Escalate and Continue Incident Response]

22. Version History

Version	Date	Author	Changes
0.1	2026-06-17	Head of Engineering	Initial draft.
1.0	2026-06-22	Head of Engineering	Active.
1.1	2026-06-23	Head of Engineering	Aligned QA failure path with Reopened status.