Documentation Deployment Runbook

Use this runbook to deploy the documentation site to its Dev or Test environment. Deployments originate from builds on main.

Environment Mapping

GitHub environment	Image repository	Audience	Approval	Verification URL
Dev	docs-merchant	Merchant-safe documentation	Required	docs.healthsafepay.com
Test	docs-internal	Full internal documentation	Not required	developers.healthsafepay.com

The environment selects its Helm values file and image repository. Deploy the merchant image only to Dev and the internal image only to Test.

Dev deployment approval is configured in the GitHub Environment because docs.healthsafepay.com is merchant-facing. Test deployments to developers.healthsafepay.com do not require GitHub Environment approval.

Automatic Deployment

Use the automatic path after a successful push to main.

1. Confirm the applicable build workflow completed successfully:
   • build-merchant.yml produces the docs-merchant image for Dev.
   • build-internal.yml produces the docs-internal image for Test.
2. Open the build's GitHub issue labelled deployment-requested.
3. Confirm the issue targets the expected environment. For an internal build, wait for fix-deployment-issue to change the target from Dev to Test.
4. Add the /deploy comment to start deploy.yml.
5. For Dev, approve the GitHub Environment deployment request when prompted. For Test, no GitHub Environment approval is required.
6. Wait for the deployment workflow to finish successfully.
7. Open the verification URL and confirm the deployed documentation change is present.

Manual Deployment

Use a manual deployment to retry a failed deployment, deploy a known build, or roll back.

Before starting, locate the short commit SHA from a successful build in the image repository for the target environment.

1. Open deploy-manually in GitHub Actions.
2. Select Run workflow.
3. Select Dev for docs-merchant or Test for docs-internal.
4. Enter the image tag as the short commit SHA, for example a0b93c6.
5. Start the workflow. Approve the GitHub Environment request for Dev when prompted; Test does not require approval.
6. Wait for the workflow to complete successfully.
7. Open the matching verification URL and confirm both the expected audience and documentation change.

Rollback

1. Identify the short commit SHA for the last known good build in the target environment's image repository.
2. Run deploy-manually with the affected environment and that image tag.
3. Wait for the workflow to finish successfully.
4. Verify the matching environment URL.
5. Record the failed deployment run and tag before retrying a newer build.

Troubleshooting

Symptom	Action
Build did not create a usable image	Open the failed build-merchant.yml or build-internal.yml run and resolve the build failure before deploying.
Deployment workflow fails	Review the failed workflow run, confirm the selected environment and image tag, then retry with the last known good tag if a rollback is required.
Pod does not start	Check the pod logs in the matching namespace: checkout-domain-dev or checkout-domain-test.
Image cannot be pulled	Confirm the tag exists in the corresponding ACR repository: docs-merchant for Dev or docs-internal for Test.