Operational Runbook

Report Builder Service: Release

How to deploy a new version of the Report Builder service safely, verify it, and roll back if needed.

Document ID RB-OPS-007

Version 1.4

Service Report Builder API

Owner Platform Team

On-call #report-builder-oncall

Typical duration 15 to 20 minutes

This is a technical writing sample. It documents a representative deployment runbook for the same service shown in the API reference sample, demonstrating step-by-step procedure, verification, and rollback. It is not tied to any real system.

1Overview

Use this runbook to release a new version of the Report Builder service to production. It assumes the change has already passed code review and staging tests. The procedure is written so that any on-call engineer can run it without prior context, and so that a rollback is always one clearly defined step away.

Before you start. Confirm there is no active incident and no change freeze in effect. If either applies, stop and coordinate with the service owner.

2Prerequisites

Requirement	Detail
Access	Deploy permission for the `report-builder` service and access to the production dashboard.
Tools	The deploy CLI installed and authenticated, plus access to logs and metrics.
Release	A build tagged for release and an approved change record.
Communication	Access to the team channel to post start and completion notices.

3Pre-deployment checklist

The release build has passed CI and staging verification.
The change record is approved and linked.
No active incident or change freeze is in effect.
The current production version is recorded for rollback (see step 4.1).
A start notice is posted to the team channel.

4Deployment procedure

4.1 Record the current version

Capture the version currently running so you can roll back to it precisely if needed.

rb-deploy status --env production

Note the reported version, for example v1.8.2, before continuing.

4.2 Deploy the new version

Start the rollout. The service deploys gradually so a problem can be caught before it reaches all traffic.

rb-deploy release --env production --version v1.9.0

The command reports progress as each batch of instances updates. Wait for it to report rollout complete before moving on.

4.3 Confirm the rollout

rb-deploy status --env production

Confirm the reported version now matches the version you deployed and that all instances are healthy.

5Verification

Run these smoke tests against production before declaring the release successful.

Call the health endpoint and confirm a 200 response:
```
curl https://api.example.com/v1/health
```
Create a test report and confirm a 201 Created response with a valid id. (See the API reference for the request format.)
Retrieve the test report by its ID and confirm the details match.
Check the dashboard: error rate, latency, and request volume should return to their normal range within five minutes.

Definition of done. The release is successful when the version matches, all smoke tests pass, and metrics are within the normal range. Post a completion notice to the team channel and close the change record.

6Rollback

Roll back immediately if any smoke test fails, the error rate climbs above its normal range, or latency degrades and does not recover within five minutes. Do not attempt to debug forward in production.

Roll back to the version you recorded in step 4.1.

rb-deploy rollback --env production --to v1.8.2

Wait for the command to report rollback complete.
Re-run the verification steps in section 5 against the restored version.
Post a notice that a rollback occurred, and open a follow-up to investigate the failed release.

7Escalation

If the rollback does not restore healthy service, or if customer-facing impact continues, escalate without delay.

Situation	Action
Rollback succeeded, release failed	Open a follow-up issue and notify the service owner during business hours.
Rollback did not restore service	Page the secondary on-call and the service owner immediately, and declare an incident.
Customer-facing data or privacy concern	Declare an incident and notify the on-call lead at once, regardless of time.

8Revision history

Version	Summary of change	Owner
1.4	Added the explicit rollback triggers and the escalation table.	Platform Team
1.3	Expanded verification to include the create and retrieve smoke tests.	Platform Team
1.0	Initial deployment and rollback procedure.	Platform Team