Multi-Environment Config Promotion¶

Workbench configuration changes move through a standard set of environments before reaching production. This page explains each environment's purpose, how to deploy to each one via the Send Partner Portal, and how to avoid common pitfalls.

Environment stages¶

Environment	Purpose	Who deploys
Local (PDE)	Individual developer testing — no deployment needed	Developer (Docker Compose)
Dev	Shared integration testing — branch-based deployments, no version tagging required	Configurator via Partner Portal
SIT	System Integration Testing — version tag-based, requires sign-off before UAT	Configurator via Partner Portal
UAT	User Acceptance Testing — final sign-off stage before production	Configurator via Partner Portal
Production	Live client environment — managed release process	Send release management team

Dev is the most permissive environment — any branch can be deployed and there are no daily deployment limits per se, though approximately 6–10 minutes of downtime is expected per deployment. SIT and UAT require a tagged client microservice version (created via the portal) and DynamoDB changes must always be deployed before the microservice version.

Production deployments are not self-service. They follow the Send release management team's scheduled process and require formal sign-off from UAT.

The Send Partner Portal¶

All non-local deployments are requested through the Send Partner Portal — a self-service Jira-based request system.

URL: https://send-partner-portal.refined.site

Request Type	When to Use
Client Build & Deploy	Deploy a branch to the Dev environment — no version tag needed
Create Client Microservice Version	Tag a version of the client microservice for deployment to SIT or UAT
Deploy Client Microservice Version	Deploy a tagged client microservice version to SIT or UAT
Deploy DynamoDB Changes	Deploy `dynamodb/{env}/data.json` changes to any environment (Dev, SIT, UAT)
Workbench Core Deployment	Deploy a new version of the Workbench core (not client config — managed by Send)
Workbench Restart	Restart services in an environment without a new deployment
Create Client Hotfix	Initiate a hotfix for an urgent production issue (branch must be prefixed `hotfix/`)
Create Core Hotfix Version	Initiate a Workbench core hotfix
Deploy Core Hotfix	Deploy a core hotfix to an environment

See the Partner Portal Reference for full details on each request type.

The two config tracks¶

Configuration in Workbench splits into two domains. It is critical to understand which track a given change belongs to.

Track 1 — Business config (S3)¶

Everything in the client config repository except the dynamodb/ directory is S3 business config:

config/{client}/
  actions/
  applicationconfig/
  business-class/
  business-constants/
  document-clause/
  document-template/
  dua/
  pipelines/
  questions/
  roles/
  rules/
  screen-meta-data/
  task-templates/
  trading-parties/
  uw-rationale/

Deploying to Dev:

Commit and push your changes to the target branch in the config repository
Raise a Client Build & Deploy request in the Partner Portal, specifying the branch
Workbench picks up business config changes on its next periodic refresh — no manual reload required

Deploying to SIT / UAT:

Merge your changes to the appropriate branch
Raise a Create Client Microservice Version request in the portal to tag a deployable version
Then raise a Deploy Client Microservice Version request to push that version to SIT or UAT
If you also have DynamoDB changes, deploy those first — see Track 2 below

Tip

The branch-to-environment mapping varies per client. Confirm with your delivery lead before your first deployment.

Track 2 — Environment config (DynamoDB)¶

The dynamodb/{environment}/data.json file defines the per-environment profile (service URLs, credentials, queue names, S3 bucket names, database endpoints). Changes to data.json:

Edit the file directly in the config repository, just like any other config file
Raise a Deploy DynamoDB Changes request in the Partner Portal
Require a service restart to take effect — this is handled as part of the portal request
Must be deployed before the client microservice version when promoting to SIT or UAT — deploying the microservice first with an incompatible DynamoDB profile will cause startup failures

Deploy DynamoDB before the microservice

When promoting to SIT or UAT, always deploy your DynamoDB changes via a Deploy DynamoDB Changes portal request before you raise the Deploy Client Microservice Version request. Reversing this order is a common cause of startup failures.

Branch strategy¶

A common branching strategy for the config repository is:

Branch	Maps to environment
`main`	Production
`uat`	UAT
`sit`	SIT
`dev`	Dev

Developers raise pull requests from feature branches into dev. Changes are promoted by merging dev → sit → uat → main through standard PR review. After each merge, raise the appropriate portal request to deploy the updated config to the target environment.

Warning

Merging directly to main bypasses UAT sign-off. Guard the main branch with required reviewers and do not allow direct pushes.

Hotfixes¶

When an urgent production issue requires a fix that cannot wait for the standard promotion path:

Create a branch from main prefixed with hotfix/ (e.g. hotfix/fix-sanctions-check)
Apply the fix and raise a Create Client Hotfix request in the Partner Portal
The hotfix bypasses the normal SIT/UAT promotion path
Once deployed to production, back-merge the hotfix branch into uat, sit, and dev immediately to prevent drift

Config drift and how to prevent it¶

Config drift occurs when UAT or production contains configuration that Dev does not — or vice versa. Common causes:

Hotfixes applied directly to main or uat without back-merging to dev
DynamoDB changes deployed to one environment but not committed or promoted to others
Long-lived feature branches that fall behind the base branch

Preventing drift in business config: Use a strict forward-promotion policy — all changes go through dev first. Any hotfix merged to main must immediately be back-merged to uat, sit, and dev.

Preventing drift in environment config: The dynamodb/{environment}/data.json files in the config repository are the source of truth for each environment's profile. Keep them up to date as you make changes. After the portal request completes, confirm the applied values match what is committed in the repo.

What needs a restart vs. a reload¶

Change type	How to apply
Any file in `config/{client}/` (incl. `be_config.json`, `ui_config.json`) — Dev	Client Build & Deploy portal request; periodic refresh
Any file in `config/{client}/` (incl. `be_config.json`, `ui_config.json`) — SIT/UAT	Create Client Microservice Version then Deploy Client Microservice Version portal requests
`dynamodb/{env}/data.json`	Deploy DynamoDB Changes portal request; service restart included
New pipeline definitions	Included in the standard business config deployment
Role or permission changes	Included in the standard business config deployment; periodic refresh
New feature switch in `be_config.json`	Included in the standard business config deployment; periodic refresh
Database schema migration	Applied by Send engineering; service restart

Testing config changes before promotion¶

Before promoting to SIT, validate your config changes locally:

Apply the change to your local pde.dev.json (for environment profile changes) or directly to the relevant file under config/{client}/ (for S3 business config changes)
Restart your local stack to pick up the change
Exercise the affected feature manually in the local Workbench UI
Check service logs for warnings or errors

For automated validation approaches, see Testing Configuration Changes.

Promotion checklist¶

Use this checklist when promoting a set of changes from Dev → SIT, SIT → UAT, or UAT → Production:

[ ] All feature branches merged and conflicts resolved
[ ] Config successfully deployed and validated in source environment — no errors in logs
[ ] Manual smoke test completed in source environment
[ ] PR reviewed and approved by at least one other engineer
[ ] If DynamoDB changes are included: Deploy DynamoDB Changes portal request raised and completed before microservice deployment
[ ] Dependent changes (e.g. new business constant used by a new form field) promoted together
[ ] Document templates and clause library updated if document generation changed
[ ] dynamodb/{environment}/data.json reference file up to date in config repo for all target environments
[ ] For SIT/UAT: Create Client Microservice Version raised and version tag confirmed
[ ] For SIT/UAT: Deploy Client Microservice Version portal request raised after DynamoDB deployment
[ ] For Production: formal sign-off from UAT provided to Send release management team