TUTORIAL 08

Release & Deploy

Sprint 3 is complete. 8 stories merged to develop. Time to ship v2.0.0.

⏱ ~15 min · Hands-on

/agile-code-branch /agile-code-merge /agile-ship-release /agile-security-scan /agile-code-ci /agile-ship-changelog /agile-ship-deploy /agile-ship-rollback
Scenario

Sprint 3 just wrapped. The team completed 8 user stories on the develop branch: task filtering, user permissions, notification preferences, and more. All stories passed their Definition of Done. It's time to cut a release and ship to production.

Step 1: Create the Release Branch

A release branch freezes the feature set. From this point, only bug fixes are allowed — no new features.

/agile-code-branch release/v2.0.0 --from develop
Branch created: release/v2.0.0 (from develop)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Base branch: develop (up to date)
Switched to: release/v2.0.0
Tracking: origin/release/v2.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Ready — release branch created from develop
Release Branch Rule

Only bug fixes are allowed on the release branch. No new features, no refactoring, no experiments. If a feature isn't ready, it stays on develop for the next release.

Step 2: Full CI Pipeline

Run the complete pipeline on the release branch to verify everything works together.

/agile-code-ci
CI Pipeline — release/v2.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Build .................. ✅ PASS (18s)
Unit Tests ............. ✅ 142/142 passing (41s)
Integration Tests ...... ✅ 24/24 passing (33s)
E2E Tests .............. ✅ 12/12 passing (67s)
Lint ................... ✅ 0 issues
Code Coverage .......... ✅ 84% (threshold: 80%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Result: ✅ ALL CHECKS PASSED

Step 3: Security Scan

Before any production release, scan dependencies for known vulnerabilities.

/agile-security-scan
Security Scan — release/v2.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Dependencies scanned: 87
Vulnerabilities found:

  🔴 Critical:  0
  🟠 High:      0
  🟡 Medium:    1
  🔵 Low:       0

Details:
  🟡 lodash@4.17.20 — Prototype Pollution (CVE-2021-23337)
     Severity: Medium
     Fix: upgrade to lodash@4.17.21

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Action Required: 1 medium vulnerability

Fix the Vulnerability

npm update lodash
# or
npm install lodash@4.17.21

Re-scan to confirm:

/agile-security-scan
Dependencies scanned: 87
Vulnerabilities found: 0

✅ CLEAN — no known vulnerabilities

Step 4: QA on Staging

Deploy the release branch to the staging environment. @qa runs exploratory testing.

QA Report

Exploratory Testing — staging/v2.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Tested flows:
  ✅ User registration and login
  ✅ Task creation and editing
  ✅ Task filtering by status (new feature)
  ✅ User permissions (new feature)
  ✅ Notification preferences (new feature)
  ❌ Task export to CSV — date format incorrect

Bug found:
  BUG-078: CSV export uses MM/DD/YYYY instead of ISO 8601
  Severity: Minor
  Fix: Update date formatter in CsvExporter

Fix the bug on the release branch:

/agile-code-commit
fix(export): use ISO 8601 date format in CSV export
⚠️ Bug Fixes Only

This fix is allowed because it's a bug. If @qa had requested a new "export to PDF" feature, it would be rejected — new features go into the next sprint, not the release branch.

Step 5: Version Bump

Update the version number in your project manifest.

# package.json
{
  "name": "task-manager",
  "version": "2.0.0",
  ...
}
/agile-code-commit
chore(release): bump version to 2.0.0

Step 6: Generate Changelog with /agile-ship-changelog

Before cutting the release, generate a structured changelog from all the commits on the release branch:

/agile-ship-changelog

CHANGELOG — v2.0.0

## v2.0.0 (2026-04-04)

### Features
- feat(tasks): add task filtering by status (#42)
- feat(users): role-based permission system (#45)
- feat(notifications): user notification preferences (#48)
- feat(tasks): bulk task operations (#50)
- feat(dashboard): sprint velocity chart (#51)

### Bug Fixes
- fix(export): use ISO 8601 date format in CSV export (#BUG-078)
- fix(auth): session timeout now respects user timezone (#BUG-071)

### Security
- chore(deps): upgrade lodash to 4.17.21 (CVE-2021-23337)

### Internal
- refactor(user): split UserService into focused services
- test: increase coverage from 72% to 84%
/agile-ship-changelog vs. /agile-ship-release

/agile-ship-changelog generates the changelog from commit history — grouping by type (features, fixes, security, internal) and linking to PRs. /agile-ship-release handles the broader release process including version bumping and tagging. Use changelog first to review what's included, then release to finalize.

Step 6b: Finalize the Release

/agile-ship-release

This command finalizes the release — applying the version tag and preparing the release artifacts.

Step 7: Merge the Release Branch

A release branch must merge to both main (production) and develop (so bug fixes flow back). The /agile-code-merge command handles the complete release merge workflow in one step: merge to main, merge to develop, tag, push, and clean up the branch.

/agile-code-merge release/v2.0.0
Merge — release/v2.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Detected: release branch → merging to main + develop

Merge to main:
  Strategy: --no-ff (preserves branch history)
  Commit: Merge branch 'release/v2.0.0' into main
  Result .................. ✅ merged

Merge to develop:
  Strategy: --no-ff (preserves branch history)
  Commit: Merge branch 'release/v2.0.0' into develop
  Result .................. ✅ merged

Tag:
  Created: v2.0.0 (annotated)
  Message: "Release v2.0.0"
  Result .................. ✅ tagged

Push:
  main .................... ✅ pushed
  develop ................. ✅ pushed
  v2.0.0 .................. ✅ pushed

Cleanup:
  Local branch ............ ✅ deleted release/v2.0.0
  Remote branch ........... ✅ deleted origin/release/v2.0.0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Release v2.0.0 merged, tagged, and cleaned up
Both Merges Are Mandatory

Just like hotfixes, a release branch merges to both main and develop. /agile-code-merge detects the release/ prefix and automatically performs both merges. Skipping the develop merge would mean the CSV date fix (BUG-078) and the lodash upgrade are lost in future development.

What /agile-code-merge does for release branches

/agile-code-merge recognizes the release/ prefix and performs the full release merge flow: merge to main with --no-ff (preserving branch history), merge to develop with --no-ff, create an annotated tag from the version in the branch name, push all changes, and delete the release branch locally and on the remote.

Step 8: Deploy to Production

/agile-ship-deploy
Deploy — v2.0.0 → production
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pre-deploy checks:
  Tag exists .............. ✅ v2.0.0
  CI passed ............... ✅ all green
  Security scan ........... ✅ 0 vulnerabilities
  QA sign-off ............. ✅ approved

Rolling deploy:
  pod-1/4 ................. ✅ healthy
  pod-2/4 ................. ✅ healthy
  pod-3/4 ................. ✅ healthy
  pod-4/4 ................. ✅ healthy

Post-deploy validation:
  Health checks ........... ✅ all endpoints responding
  Smoke test: login ....... ✅ pass
  Smoke test: tasks ....... ✅ pass
  Smoke test: filtering ... ✅ pass (new feature)
  Smoke test: export ...... ✅ pass (bug fix verified)
  Error rate .............. ✅ 0.02% (baseline: 0.03%)
  Response time p99 ....... ✅ 180ms (baseline: 195ms)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Deploy complete: v2.0.0 is LIVE
Time: 2026-04-04 14:22 UTC
If the deploy fails: /agile-ship-rollback

If health checks fail, error rates spike, or smoke tests don't pass after deploying, roll back immediately:

/agile-ship-rollback
⏪ Rollback — v2.0.0 → v1.9.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Reason: post-deploy smoke test failure
Rolling back to: v1.9.0 (last known good)

  pod-1/4 ............. ✅ rolled back
  pod-2/4 ............. ✅ rolled back
  pod-3/4 ............. ✅ rolled back
  pod-4/4 ............. ✅ rolled back

Health checks ......... ✅ all endpoints responding
Error rate ............ ✅ returned to baseline

Rollback complete. Production is on v1.9.0.
⚠️ Investigate and fix the issue on the release branch before re-deploying.

Always have a rollback plan before deploying. /agile-ship-rollback reverts production to the previous version in seconds. It's faster and safer than debugging a broken deploy in production.

Step 9: Notify Stakeholders

The release branch was already cleaned up by /agile-code-merge in Step 7. All that's left is notifying stakeholders:

📢 Release Notification — v2.0.0

Task Manager v2.0.0 is now live in production.

New features:
• Task filtering by status
• Role-based permissions
• Notification preferences
• Bulk task operations
• Sprint velocity chart

Bug fixes: 2 resolved
Security: lodash upgraded (CVE-2021-23337)

Release notes: https://github.com/team/task-manager/releases/v2.0.0

Release Flow

🌿
/agile-code-branch release from develop
⚙️
/agile-code-ci full pipeline
🔒
/agile-security-scan dep check
🧪
QA staging test
🔢
Version Bump changelog
🔀
/agile-code-merge main + develop + tag
🚀
/agile-ship-deploy production

What You Practiced

Knowledge Check

Where does a release branch merge?