Release Orchestrator
April 2, 2026 ยท View on GitHub
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