How Software Teams Write SOPs for Releases and Deployments

The vast majority of engineering teams have automated their builds, but the work around them is still manual. Someone tags the release, updates the changelog, turns the feature flag on, posts in the release channel and then keeps an eye on the dashboards. If that person is on holiday, the release slips or goes out with a step missed.

Standard operating procedures (SOPs) fill the gap between what your CI/CD pipeline does and what people still have to do. For distributed and outsourced teams, they’re often the difference between a smooth handover and a weekend incident.

Which engineering processes need SOPs

You don’t need an SOP for everything. Focus on the tasks that are infrequent, high-risk and/or done by different people each time:

Release process: versioning, tagging, changelog, approvals and announcements.
Production deployment: pre-checks, deployment steps, verification and rollback.
Hotfix process: branching strategy, accelerated review and backporting.
Database migrations: backups, dry runs, maintenance windows and rollback scripts.
On-call handover: what to check, where alerts route and how to escalate.
Access requests: granting and revoking of repository, cloud and production access.
New developer setup: local environment, secrets management and that first PR.

Anatomy of a good engineering SOP

# SOP: Production deployment (web app)
Owner: Platform team · Last reviewed: YYYY-MM-DD

## When to use
Scheduled releases from main. Not for hotfixes (see Hotfix SOP).

## Prerequisites
- Release PR approved by 2 reviewers
- CI green on main
- Release notes drafted

## Steps
1. Announce the deployment in #releases
2. Trigger the deploy workflow for the release tag
3. Watch error rate and latency dashboards for 15 minutes
4. Mark the release as deployed in the tracker

## Verification
- Smoke tests pass
- No error-rate spike above baseline

## Rollback
1. Re-run deploy workflow with previous tag
2. Post rollback notice in #releases and open an incident

The structure is more important than the tool. Every SOP has to have a clear trigger, a set of prerequisites, a series of numbered steps, a verification step and a rollback.

Keep SOPs close to the code

Store text SOPs in the repository as Markdown, alongside the code that they describe. They get reviewed in PRs just like any other change.
Link SOPs from where the work actually happens: the PR template, the deploy workflow’s description and the on-call runbook.
Automate what you can, document what you can’t. If a step can be scripted, script it and reference it in the SOP.

When text isn’t enough

Markdown is great for CLI steps and decision logic. It’s not so good for anything that’s done in a web console (a cloud provider’s dashboard, a feature flag service, an app store submission, a third-party admin panel and so on). Those interfaces are constantly in flux, and a paragraph describing “the toggle in the top right of the environment settings” will quickly go out of date.

For console-based steps, short recorded walkthroughs are the way to go. Capture tools such as Guideless will record the steps as you go through them in the browser and create a narrated video guide with the written steps, which you can then link from your Markdown SOP or export as Markdown. Secrets and internal URLs can be blurred before sharing. When the console changes, you simply replace the relevant step rather than re-recording the whole thing.

SOPs for outsourced and distributed teams

When development is shared between an in-house team and an outsourcing partner, the SOPs become part of the contract in practice:

Define ownership. For each process, state which team owns it and who approves it.
Make onboarding self-serve. A new engineer on the partner side should be able to set up, build and deploy from documented steps without having to wait for a meeting across time zones.
Use SOPs as the vehicle for knowledge transfer. At the end of an engagement or a team rotation, an up-to-date SOP is your most reliable handover artifact.

Keeping SOPs from going stale

Add “update affected SOPs” to your definition of done for any pipeline or infrastructure changes.
Review the SOPs after every incident where a documented step was wrong or missing.
Put a “last reviewed” date at the top, and treat anything older than 6 months as suspect.

Final thoughts

Good engineering SOPs are short, structured and maintained like code. Write them for the person doing the task for the first time, keep them where the developers already work and record console-based steps rather than describing them. Your releases get a lot calmer, and your team stops relying on whoever happens to remember.

Author
Recent Posts

Bogdan Sandu

Bogdan Sandu is a front-end developer at TMS Outsource with 8+ years of experience in web technologies. He writes about developer tools, software platforms, and web workflows based on daily hands-on use.