Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

chore(ci): automate version bumps with release-please (#181)

Rufusbf8bee058d28
diff --git a/.github/workflows/release-images.yml b/.github/workflows/release-images.yml
index 7e9da5da..e52abe76 100644
--- a/.github/workflows/release-images.yml
+++ b/.github/workflows/release-images.yml
@@ -19,9 +19,11 @@
# hardcoded ghcr.io/sentelabsai/* names. A fork that wants its own images
# changes the guard and the image names.
#
-# A `vX.Y.Z` tag also creates the GitHub Release once both images are
-# published, using that version's CHANGELOG.md section as the notes, so the
-# changelog entry must be merged before the commit is tagged. A tag alone
+# Version tags normally come from merging the release PR that
+# release-please.yml maintains; that also creates the GitHub Release. For a
+# tag pushed by hand, a `vX.Y.Z` tag also creates the GitHub Release once both
+# images are published, using that version's CHANGELOG.md section as the
+# notes, so the changelog entry must be merged before the commit is tagged. A tag alone
# never shows under Releases. If the images fail, no release is created; if a
# release for the tag already exists (made by hand), the job leaves it alone.
#
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
new file mode 100644
index 00000000..287f8c6b
--- /dev/null
+++ b/.github/workflows/release-please.yml
@@ -0,0 +1,58 @@
+# Keep a standing release PR, and cut the release when it merges.
+#
+# Every push to main runs release-please. PRs are squash-merged with the PR
+# title as the commit subject, so it reads the PR titles merged since the
+# last release (`feat` → minor, `fix` → patch; before
+# 1.0 a breaking change is also a minor) and opens or updates one PR titled
+# "chore(main): release X.Y.Z". That PR bumps every place the version is
+# written (see release-please-config.json) and adds the CHANGELOG.md entry.
+# Merges that are only chore/docs/test/refactor do not start a release on
+# their own; they ride along with the next feat or fix.
+#
+# Merging the release PR makes this workflow tag the merge commit `vX.Y.Z`
+# and create the GitHub Release from the changelog entry. The tag push then
+# runs release-images.yml, which publishes the images (its own release job
+# sees the release already exists and leaves it alone).
+#
+# Token: this uses the RELEASE_PLEASE_TOKEN secret, not GITHUB_TOKEN. GitHub
+# does not start workflows from events made with GITHUB_TOKEN, so with it the
+# release PR would get no CI runs (and could not satisfy required checks) and
+# the release tag would publish no images. Use a fine-grained token scoped to
+# this repository with Contents and Pull requests read/write.
+#
+# Guarded to this repository for the same reason as release-images.yml: the
+# saas fork merges upstream/main and must not open release PRs of its own.
+name: Release please
+
+on:
+ push:
+ branches: [main]
+
+permissions:
+ contents: read
+
+# One run at a time, in order, so two quick merges cannot race on the
+# release PR branch.
+concurrency:
+ group: ${{ github.workflow }}
+ cancel-in-progress: false
+
+jobs:
+ release-please:
+ if: github.repository == 'SenteLabsAI/OpenExecutive'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Require the release token
+ env:
+ HAS_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN != '' }}
+ run: |
+ if [ "$HAS_TOKEN" != "true" ]; then
+ echo "::error::Set the RELEASE_PLEASE_TOKEN repository secret (see the header of .github/workflows/release-please.yml)."
+ exit 1
+ fi
+
+ - uses: googleapis/release-please-action@v4
+ with:
+ token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+ config-file: release-please-config.json
+ manifest-file: .release-please-manifest.json
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
new file mode 100644
index 00000000..0ee8c012
--- /dev/null
+++ b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+ ".": "0.3.0"
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 216fb7c2..50ad4f3c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,9 @@ All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-## [Unreleased]
+From 0.3.0 on, entries are written by release-please from the titles of the
+merged pull requests (`feat` → Added, `fix` → Fixed). The open release PR holds
+the next entry; edit it there before merging if a line needs rewording.
## [0.3.0] - 2026-09-23
@@ -442,7 +444,6 @@ Initial public release.
- Open-source project setup: Apache-2.0 license, contribution guide, code of
conduct, security policy, issue/PR templates, and CI.
-[Unreleased]: https://github.com/SenteLabsAI/OpenExecutive/compare/v0.3.0...HEAD
[0.3.0]: https://github.com/SenteLabsAI/OpenExecutive/compare/v0.2.2...v0.3.0
[0.2.2]: https://github.com/SenteLabsAI/OpenExecutive/compare/v0.2.1...v0.2.2
[0.2.1]: https://github.com/SenteLabsAI/OpenExecutive/compare/v0.2.0...v0.2.1
diff --git a/CLAUDE.md b/CLAUDE.md
index dfdab619..0ca5abce 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -217,6 +217,12 @@ cd evals && python run_evals.py --scenarios scenarios/ --output results/
`ui`, `deps`, …), not a file path; drop it only when the change genuinely
spans the repo. Say what changed rather than what it is about, lowercase
after the colon, no trailing period. See `.github/PULL_REQUEST_TEMPLATE.md`.
+ The type sets the next version (release-please: `feat` → minor, `fix` →
+ patch; `chore`/`docs`/`test`/`refactor` release nothing on their own), and
+ `feat`/`fix` titles become the changelog lines, so pick the type by what the
+ change is, not by how big it is. PRs are squash-merged with the PR title as
+ the commit subject, which is what release-please reads — branch commit
+ messages do not reach `main`.
- PR description is three sections and nothing else: **Problem**, **Approach**,
**Checklist** (see `.github/PULL_REQUEST_TEMPLATE.md`). Rationale, review
findings and alternatives go in the commit message; open questions go in the
diff --git a/docs/deployment.md b/docs/deployment.md
index 59a0954c..f79b930d 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -60,25 +60,39 @@ thing that builds `Dockerfile.ui`.
| `sha-<short>` | every push | The commit the image was built from. |
| `buildcache` | every push | BuildKit layer cache. Not an image; ignore it. |
-**Cutting a release** is pushing a `vX.Y.Z` tag:
-
-```bash
-git tag v0.2.0 && git push origin v0.2.0
-```
-
-The workflow runs on the tag push and publishes the versioned tags. It does
-not check CI: it publishes whatever commit the tag points at, and the `main`
-tag is published in parallel with CI on every push, so tag only a commit on
-`main` that CI has passed. The two images are separate jobs, so a release is
-not atomic — if one fails, check the package pages and re-run the failed job
-from the Actions UI. Nothing bumps the version strings in
-`packages/core/pyproject.toml` or `packages/ui/package.json` for you; update
-them in the release commit.
+**Cutting a release** is merging the release PR.
+[.github/workflows/release-please.yml](../.github/workflows/release-please.yml)
+runs release-please on every push to `main` and keeps one open PR,
+"chore(main): release X.Y.Z", up to date. PRs are squash-merged, so each one
+lands as a single commit whose subject is the PR title, and the version comes
+from those titles' conventional-commit types since the last release: `feat` → minor,
+`fix` → patch, and before 1.0 a breaking change is also a minor. The PR bumps
+every place the version is written (listed in `release-please-config.json`)
+and adds the `CHANGELOG.md` entry, which can be edited in the PR before
+merging. Merges that are only `chore`/`docs`/`test`/`refactor` wait for the
+next `feat` or `fix`. Merging the release PR tags the merge commit `vX.Y.Z`
+and creates the GitHub Release; the tag push then runs the image workflow.
+It needs the `RELEASE_PLEASE_TOKEN` repository secret (a fine-grained token
+for this repository with Contents and Pull requests read/write), because
+events made with the default `GITHUB_TOKEN` start no workflows: without it
+the release PR would get no CI and the tag would publish no images.
+
+Pushing a `vX.Y.Z` tag by hand still works (`git tag v0.3.0 && git push
+origin v0.3.0`) but bypasses the version bump and changelog, so the release
+PR is the normal path.
+
+The image workflow runs on the tag push and publishes the versioned tags. It
+does not check CI: it publishes whatever commit the tag points at, and the
+`main` tag is published in parallel with CI on every push, so the release PR
+should only be merged once its CI is green. The two images are separate jobs,
+so a release is not atomic — if one fails, check the package pages and re-run
+the failed job from the Actions UI.
Once both images are published, the same run creates the GitHub Release for
-the tag, with that version's `CHANGELOG.md` section as the notes. So merge the
-changelog entry before tagging: a tag with no `## [X.Y.Z]` section fails that
-job instead of publishing an empty release. If the images fail, no release is
+the tag if it does not exist yet (release-please normally already made it),
+with that version's `CHANGELOG.md` section as the notes. A hand-pushed tag
+with no `## [X.Y.Z]` section fails that job instead of publishing an empty
+release. If the images fail, no release is
created; re-running the failed job from the Actions UI creates it once the
images succeed. A release that already exists for the tag is left alone.
diff --git a/packages/core/openexecutive/api/main.py b/packages/core/openexecutive/api/main.py
index 7e4e7a2c..58bb1c6e 100644
--- a/packages/core/openexecutive/api/main.py
+++ b/packages/core/openexecutive/api/main.py
@@ -757,7 +757,7 @@ def create_app() -> FastAPI:
app = FastAPI(
title="Open Executive API",
description="AI-powered virtual executive team",
- version="0.3.0",
+ version="0.3.0", # x-release-please-version
lifespan=lifespan,
)
diff --git a/packages/core/openexecutive/api/models.py b/packages/core/openexecutive/api/models.py
index 71835956..a2e688aa 100644
--- a/packages/core/openexecutive/api/models.py
+++ b/packages/core/openexecutive/api/models.py
@@ -124,7 +124,7 @@ class HealthResponse(BaseModel):
company_name: str | None = None
builtin_skills: int = 0
company_skills: int = 0
- version: str = "0.3.0"
+ version: str = "0.3.0" # x-release-please-version
class SkillMeta(BaseModel):
diff --git a/packages/ui/package.json b/packages/ui/package.json
index f1ac5e43..ccc28b8d 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -2,7 +2,7 @@
"name": "open-executive-ui",
"version": "0.3.0",
"private": true,
- "description": "Next.js 15 web UI for Open Executive \u2014 an AI-powered virtual executive team.",
+ "description": "Next.js 15 web UI for Open Executive — an AI-powered virtual executive team.",
"license": "Apache-2.0",
"repository": {
"type": "git",
diff --git a/release-please-config.json b/release-please-config.json
new file mode 100644
index 00000000..79dc8f30
--- /dev/null
+++ b/release-please-config.json
@@ -0,0 +1,34 @@
+{
+ "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+ "bootstrap-sha": "98d78c7dccf74b8ea294e78c4e5be4c2f0024f63",
+ "include-component-in-tag": false,
+ "include-v-in-tag": true,
+ "packages": {
+ ".": {
+ "release-type": "simple",
+ "package-name": "openexecutive",
+ "changelog-path": "CHANGELOG.md",
+ "bump-minor-pre-major": true,
+ "bump-patch-for-minor-pre-major": false,
+ "changelog-sections": [
+ { "type": "feat", "section": "Added" },
+ { "type": "fix", "section": "Fixed" },
+ { "type": "perf", "section": "Changed" },
+ { "type": "revert", "section": "Reverted" },
+ { "type": "refactor", "section": "Changed", "hidden": true },
+ { "type": "docs", "section": "Documentation", "hidden": true },
+ { "type": "test", "section": "Tests", "hidden": true },
+ { "type": "chore", "section": "Chores", "hidden": true }
+ ],
+ "extra-files": [
+ { "type": "toml", "path": "packages/core/pyproject.toml", "jsonpath": "$.project.version" },
+ { "type": "toml", "path": "packages/core/uv.lock", "jsonpath": "$.package[?(@.name.value==='openexecutive')].version" },
+ { "type": "json", "path": "packages/ui/package.json", "jsonpath": "$.version" },
+ { "type": "json", "path": "packages/ui/package-lock.json", "jsonpath": "$.version" },
+ { "type": "json", "path": "packages/ui/package-lock.json", "jsonpath": "$.packages[''].version" },
+ { "type": "generic", "path": "packages/core/openexecutive/api/main.py" },
+ { "type": "generic", "path": "packages/core/openexecutive/api/models.py" }
+ ]
+ }
+ }
+}