Release Orchestrator

The agent runs pre-flight validation, generates changelogs from conventional commits, auto-bumps semantic versions, and scores deployment readiness with a GO/CONDITIONAL/NO-GO decision.

Quick Start

# Pre-flight: branch sync, secrets, conflicts, commits, deps
python scripts/preflight_checker.py --repo . --base main --verbose

# Changelog from conventional commits
python scripts/changelog_generator.py --repo . --from v1.2.0 --to HEAD

# Auto-detect version bump from commit history
python scripts/version_bumper.py --repo . --dry-run

# Score deployment readiness (7 categories, weighted)
python scripts/release_readiness_scorer.py --input release_data.json --json

Tools Overview

Tool	Input	Output
`preflight_checker.py`	Repo path + base branch	Pass/fail on 7 checks (sync, conflicts, secrets, commits, deps)
`changelog_generator.py`	Git repo + ref range	Keep a Changelog markdown with commit grouping
`version_bumper.py`	Repo path	Next semver from commit analysis; updates version files
`release_readiness_scorer.py`	Release data JSON	Score 0-100, GO/CONDITIONAL/NO-GO decision

All tools support --json for machine output. Exit code 0 = pass, 1 = fail (CI-friendly).

Workflow 1: Pre-Flight Validation

python scripts/preflight_checker.py --repo . --base main --json

The agent runs seven automated checks:

Branch sync -- local branch up to date with remote base
Merge conflicts -- dry-run merge to detect conflicts
Uncommitted changes -- fail if working tree is dirty
Secret scanning -- pattern-match for API keys, tokens, passwords (AWS, GCP, GitHub, Stripe, JWT)
Gitignore validation -- .env, credential files covered
Conventional commits -- recent commits follow type(scope): description
Dependency audit -- lock file consistency (package-lock.json, poetry.lock, etc.)

Validation checkpoint: All 7 checks pass. Exit code 0.

Workflow 2: Version Management and Changelog

Step 1 -- Auto-detect version bump.

python scripts/version_bumper.py --repo . --dry-run --json

Commit Type	Bump	Example
`fix:`	PATCH (0.0.x)	`fix(auth): handle expired tokens`
`feat:`	MINOR (0.x.0)	`feat(api): add pagination`
`feat!:` or `BREAKING CHANGE`	MAJOR (x.0.0)	`feat!: redesign auth flow`
`docs:`, `chore:`, `test:`	No bump	`docs: update README`

Reads from: package.json, pyproject.toml, setup.py, setup.cfg, Cargo.toml, VERSION file. Pre-release support: --pre alpha|beta|rc produces 1.3.0-rc.1.

Step 2 -- Generate changelog.

python scripts/changelog_generator.py --repo . --from latest --to HEAD --output CHANGELOG.md --full

Groups commits by type (Added, Changed, Fixed, Security, Breaking Changes) with hashes and @author attribution.

Step 3 -- Apply version bump.

python scripts/version_bumper.py --repo .  # writes to all discovered version files

Validation checkpoint: --dry-run shows expected version. Changelog covers 100% of commits.

Workflow 3: Deployment Readiness

python scripts/release_readiness_scorer.py --input release_data.json --json

The agent scores across 7 weighted categories:

Category	Weight	Measures
Tests	25%	Pass rate, coverage, flaky count
Code Quality	20%	Lint errors, type errors, complexity, duplication
Documentation	15%	README, API docs, changelog, migration guide
Security	15%	No secrets, no critical CVEs, SAST clean
Breaking Changes	10%	Documented, migration path, deprecation notices
Dependencies	10%	Lock files consistent, no yanked packages
Rollback Plan	5%	Procedure documented, DB migration reversible, feature flags

Decision thresholds:

Score	Decision	Action
80-100	GO	Proceed with deployment
60-79	CONDITIONAL	Proceed with mitigations documented
0-59	NO-GO	Address blockers first

Any single category below 40 triggers a mandatory blocker regardless of overall score.

Validation checkpoint: Score >= 80 (GO). Zero category blockers.

End-to-End Release Pipeline

Chain all workflows into a single automated pipeline:

#!/bin/bash
set -e

# Phase 1: Pre-flight
python scripts/preflight_checker.py --repo . --base main --json > /tmp/preflight.json

# Phase 2: Tests (project-specific)
python -m pytest --cov=src --cov-report=json:coverage.json -v

# Phase 3: Version bump (dry-run)
python scripts/version_bumper.py --repo . --dry-run --json > /tmp/version.json

# Phase 4: Changelog
python scripts/changelog_generator.py --repo . --from latest --to HEAD

# Phase 5: Readiness assessment
python scripts/release_readiness_scorer.py --input release_data.json --json > /tmp/readiness.json
DECISION=$(python -c "import json; print(json.load(open('/tmp/readiness.json'))['decision'])")
echo "Decision: $DECISION"

Non-interactive by default. Blocks on: pre-flight failure, test failure, or NO-GO readiness.

Release Types

Type	Branch Pattern	Bump	Notes
Hotfix	`hotfix/v1.2.1` from tag	PATCH	Minimal fix, branches from release tag
Patch	Standard flow	PATCH	Accumulated bug fixes
Minor	Standard flow	MINOR	New features, backward compatible
Major	Standard flow	MAJOR	Breaking changes, needs migration docs
Pre-release	Standard flow	`--pre alpha\|beta\|rc`	`1.3.0-alpha.1` for testing

CI/CD Integration

- name: Pre-flight Check
  run: python scripts/preflight_checker.py --repo . --base main --json > preflight.json

- name: Version Bump
  run: python scripts/version_bumper.py --repo . --dry-run --json > version.json

- name: Changelog
  run: python scripts/changelog_generator.py --repo . --from latest --to HEAD --output CHANGELOG.md

- name: Readiness Score
  run: python scripts/release_readiness_scorer.py --input release_data.json

Git hook: python scripts/preflight_checker.py --repo . --base main in .git/hooks/pre-push.

Anti-Patterns

Skipping pre-flight -- secrets ship to production. Always run pre-flight before any release work.
Manual version bumping -- leads to inconsistencies. Let commit history drive the version.
No rollback plan -- every release needs documented rollback (git revert, feature flags, or DB migration down).
Ignoring single-category blockers -- a 95 overall score with 35 Security = NO-GO.
Changelog after release -- generate before tagging so reviewers can validate.

Troubleshooting

Problem	Cause	Solution
Pre-flight "HEAD is detached"	CI checked out specific commit	Check out a named branch first
Changelog "No commits found"	`--from` ref does not exist	Verify tag with `git tag -l`; use `--since` date range
Version bumper cannot parse version	Non-semver format (e.g., `1.0`)	Use `MAJOR.MINOR.PATCH` in all manifest files
Readiness scorer exits 1 despite high score	Single category below 40-point blocker	Check BLOCKERS section; fix failing category
Secret scan false positives on test fixtures	Pattern matches example tokens	Lines with "example"/"placeholder" are skipped; move fixtures to non-tracked dir

References

Guide	Path
Release Engineering Guide	`references/release_engineering_guide.md`
Rollback Strategies	`references/rollback_strategies.md`
CI/CD Best Practices	`references/ci_cd_best_practices.md`

Integration Points

Skill	Integration
`senior-devops`	Pipeline stages consume pre-flight and readiness JSON as gates
`senior-qa`	Test results feed Tests category (25% weight)
`senior-secops`	Secret scan and CVE counts feed Security category (15%)
`code-reviewer`	Code quality metrics feed Code Quality category (20%)
`devops-workflow-engineer`	Workflow YAML calls tools as pipeline steps

Last Updated: April 2026 Version: 2.1.0

release-orchestrator