release-orchestrator · diff

v2.1.0 to v2.2.0

31 added, 206 removed. Audit A to A.

---

name: release-orchestrator

description: >

Orchestrate end-to-end release pipelines. Use when running pre-release validation,

generating changelogs, bumping semantic versions, scoring deployment readiness, or gating

releases with secret scanning and GO/NO-GO checks.

license: MIT + Commons Clause

metadata:

- version: 2.1.0

+ version: 2.2.0

author: borghei

category: engineering

domain: release-engineering

- updated: 2026-04-02

+ updated: 2026-06-17

tags: [release-pipeline, versioning, pre-flight, readiness]

python-tools: preflight_checker.py, changelog_generator.py, version_bumper.py, release_readiness_scorer.py

tech-stack: python, git, semver, conventional-commits, ci-cd

---

# 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

- ```bash

- # Pre-flight: branch sync, secrets, conflicts, commits, deps

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

+ ## Core Capabilities

- # Changelog from conventional commits

- python scripts/changelog_generator.py --repo . --from v1.2.0 --to HEAD

+ - **Pre-flight validation** — 7 automated checks: branch sync, merge conflicts, dirty tree, secret scanning (AWS/GCP/GitHub/Stripe/JWT), gitignore coverage, conventional commits, dependency lock consistency.

+ - **Version management** — auto-detect semver bump (PATCH/MINOR/MAJOR) from commit history across `package.json`, `pyproject.toml`, `Cargo.toml`, etc.; pre-release tags (`--pre alpha|beta|rc`).

+ - **Changelog generation** — Keep a Changelog markdown grouped by type (Added/Changed/Fixed/Security/Breaking) with hashes and `@author` attribution.

+ - **Deployment readiness** — weighted score across 7 categories (Tests, Code Quality, Docs, Security, Breaking Changes, Dependencies, Rollback) → GO (80+) / CONDITIONAL (60-79) / NO-GO (<60), with single-category blocker at <40.

+ - **End-to-end pipeline** — chain all tools non-interactively; blocks on pre-flight failure, test failure, or NO-GO. CI/CD steps and pre-push git hook provided.

+ - **Release types** — hotfix, patch, minor, major, and pre-release flows with branch patterns and bump rules.

- # Auto-detect version bump from commit history

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

+ ## When to Use

- # Score deployment readiness (7 categories, weighted)

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

- ```

+ - Running pre-release validation or gating a release with secret scanning and GO/NO-GO checks.

+ - Generating a changelog from conventional commits before tagging.

+ - Auto-bumping a semantic version from commit history.

+ - Scoring deployment readiness across tests, quality, security, and rollback.

+ - Wiring release validation into a CI/CD pipeline or pre-push hook.

- ## Tools Overview

+ ## Tools

- | 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 |

+ | Tool | Purpose | Command |

+ |------|---------|---------|

+ | `preflight_checker.py` | Run 7 pre-release checks (sync, conflicts, secrets, commits, deps) | `python scripts/preflight_checker.py --repo . --base main --json` |

+ | `changelog_generator.py` | Generate Keep a Changelog markdown from a ref range | `python scripts/changelog_generator.py --repo . --from v1.2.0 --to HEAD --output CHANGELOG.md` |

+ | `version_bumper.py` | Auto-detect next semver from commits; write version files | `python scripts/version_bumper.py --repo . --dry-run --json` |

+ | `release_readiness_scorer.py` | Score readiness 0-100 with GO/CONDITIONAL/NO-GO decision | `python scripts/release_readiness_scorer.py --input release_data.json --json` |

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

- ---

- ## Workflow 1: Pre-Flight Validation

- ```bash

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

- ```

- The agent runs seven automated checks:

- 1. **Branch sync** -- local branch up to date with remote base

- 2. **Merge conflicts** -- dry-run merge to detect conflicts

- 3. **Uncommitted changes** -- fail if working tree is dirty

- 4. **Secret scanning** -- pattern-match for API keys, tokens, passwords (AWS, GCP, GitHub, Stripe, JWT)

- 5. **Gitignore validation** -- `.env`, credential files covered

- 6. **Conventional commits** -- recent commits follow `type(scope): description`

- 7. **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.**

- ```bash

- 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.**

- ```bash

- 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.**

- ```bash

- 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

- ```bash

- 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:

- ```bash

- #!/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

- |------|---------------|------|-------|

- ---

- ## CI/CD Integration

- ```yaml

- - 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

- 1. **Skipping pre-flight** -- secrets ship to production. Always run pre-flight before any release work.

- 2. **Manual version bumping** -- leads to inconsistencies. Let commit history drive the version.

- 3. **No rollback plan** -- every release needs documented rollback (git revert, feature flags, or DB migration down).

- 4. **Ignoring single-category blockers** -- a 95 overall score with 35 Security = NO-GO.

- 5. **Changelog after release** -- generate before tagging so reviewers can validate.

- ---

- ## Troubleshooting

+ ## References

- | 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 |

+ Load the reference that matches the task — keep this file lean and pull detail on demand:

- ---

+ - **[references/release-workflows-and-operations.md](references/release-workflows-and-operations.md)** — quick-start commands, the three core workflows (pre-flight, version/changelog, readiness) with their checkpoint tables, the end-to-end pipeline script, release-type matrix, CI/CD integration YAML, anti-patterns, and the troubleshooting table. Read when running or chaining any workflow.

+ - **[references/release_engineering_guide.md](references/release_engineering_guide.md)** — release strategies (rolling, blue-green, canary) and release engineering practice. Read when choosing a deployment strategy.

+ - **[references/rollback_strategies.md](references/rollback_strategies.md)** — database migration rollbacks, reversible-migration rules, and rollback playbooks. Read when planning the rollback portion of a release.

+ - **[references/ci_cd_best_practices.md](references/ci_cd_best_practices.md)** — pipeline design patterns (stage-gate, fan-out/fan-in) and CI/CD best practices. Read when designing the surrounding pipeline.

- ## References

+ ## Scope & Limitations

- | 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` |

+ **This skill covers:** pre-flight validation, semantic version bumping, changelog generation, deployment-readiness scoring, and gating releases with GO/NO-GO decisions for git + conventional-commits projects.

- ---

+ **This skill does NOT cover:** the actual deploy/orchestration execution (handled by `senior-devops` / `devops-workflow-engineer`), test authoring (`senior-qa`), or deep security scanning beyond secret pattern-matching (`senior-secops`).

## 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