Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

fix(release): land qualified version PRs and resume interrupted cuts

rubenluetke10-beep3b854032014d
diff --git a/.github/workflows/release-cut.yml b/.github/workflows/release-cut.yml
index e7ad4cf911..a48b4d116e 100644
--- a/.github/workflows/release-cut.yml
+++ b/.github/workflows/release-cut.yml
@@ -7,7 +7,7 @@
# 2. bumps pyproject.toml + jarvis/__init__.py and writes the CHANGELOG
# section (scripts/ci/cut_release.py: [Unreleased] notes, or the
# Conventional Commits since the last tag),
-# 3. checks the version commit on a candidate branch, then fast-forwards main,
+# 3. checks the version commit through a candidate PR, then merges it normally,
# 4. pushes the annotated tag and dispatches the three publishing workflows
# on it (PyPI, desktop installers, signed installer). Each of them starts
# with release-gate.yml, which waits for CI on the release commit.
@@ -33,6 +33,10 @@ on:
description: "Exact version instead of a bump (optional, X.Y.Z)"
required: false
default: ""
+ resume_sha:
+ description: "Already merged and CI-qualified version commit to finish (optional full SHA)"
+ required: false
+ default: ""
concurrency:
group: release-cut
@@ -40,6 +44,7 @@ concurrency:
permissions:
contents: write
+ pull-requests: write
actions: write
checks: read
@@ -50,24 +55,42 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 180
outputs:
- version: ${{ steps.bump.outputs.version }}
+ version: ${{ steps.bump.outputs.version || steps.resume.outputs.version }}
env:
- GH_TOKEN: ${{ github.token }}
+ GH_TOKEN: ${{ secrets.INTEGRATION_TOKEN || github.token }}
+ TOKEN_IS_BOT: ${{ secrets.INTEGRATION_TOKEN == '' }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
fetch-depth: 0
+ token: ${{ secrets.INTEGRATION_TOKEN || github.token }}
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: "3.11"
- name: main must be green
+ if: inputs.resume_sha == ''
run: |
state="$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/check-runs?check_name=CI%20gate" \
--jq '(.check_runs | max_by(.id)) | if .status == "completed" then .conclusion else (.status // "missing") end')"
echo "CI gate on $GITHUB_SHA: $state"
[ "$state" = "success" ] || { echo "::error::main is not green ($state) - no release."; exit 1; }
+ - name: Select an already merged version commit
+ id: resume
+ if: inputs.resume_sha != ''
+ env:
+ RESUME_SHA: ${{ inputs.resume_sha }}
+ run: |
+ [[ "$RESUME_SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::Resume requires a full commit SHA."; exit 1; }
+ expected="$(python -c 'from scripts.ci.release_admit import versions; print(versions()[0])')"
+ # Validate ancestry before executing anything from the selected ref.
+ git merge-base --is-ancestor "$RESUME_SHA" HEAD
+ git checkout --detach "$RESUME_SHA"
+ actual="$(python -c 'from scripts.ci.release_admit import versions; print(versions()[0])')"
+ [ "$actual" = "$expected" ] || { echo "::error::Resume cannot select an older version."; exit 1; }
+ echo "version=$actual" >> "$GITHUB_OUTPUT"
- name: Bump version + CHANGELOG
id: bump
+ if: inputs.resume_sha == ''
env:
BUMP: ${{ inputs.bump }}
VERSION: ${{ inputs.version }}
@@ -77,6 +100,7 @@ jobs:
echo "version=$new" >> "$GITHUB_OUTPUT"
git diff --stat
- name: Check the version commit before landing and tagging
+ if: inputs.resume_sha == ''
env:
V: ${{ steps.bump.outputs.version }}
run: |
@@ -85,31 +109,51 @@ jobs:
git add pyproject.toml jarvis/__init__.py uv.lock CHANGELOG.md
git commit -m "chore(release): publish v$V"
sha="$(git rev-parse HEAD)"
- candidate="release-cut/v${V}-${GITHUB_RUN_ID}"
+ candidate="release-cut/v${V}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
git push origin "HEAD:refs/heads/$candidate"
- gh workflow run ci.yml --ref "$candidate" -f full=true -f include_macos=false
- # GITHUB_TOKEN pushes do not trigger CI, and protected main requires
- # checks BEFORE the push. Dispatch on this immutable candidate first.
+ # Only eligible events (here pull_request) satisfy branch protection.
+ # A workflow_dispatch CI success is not accepted by GitHub for landing.
+ if ! gh pr create --base main --head "$candidate" --title "chore(release): publish v$V" \
+ --body-file "$RUNNER_TEMP/notes.md"; then
+ echo "::notice::Repository policy may require a maintainer to open the candidate PR."
+ echo "Open https://github.com/$GITHUB_REPOSITORY/compare/main...$candidate?expand=1" >> "$GITHUB_STEP_SUMMARY"
+ fi
ci_run=""
for attempt in {1..60}; do
ci_run="$(gh run list --workflow ci.yml --branch "$candidate" --commit "$sha" \
- --event workflow_dispatch --json databaseId --jq '.[0].databaseId // empty')"
+ --event pull_request --json databaseId --jq '.[0].databaseId // empty')"
[ -n "$ci_run" ] && break
sleep 5
done
[ -n "$ci_run" ] || { echo "::error::Candidate CI did not start."; exit 1; }
+ if [ "$(gh run view "$ci_run" --json conclusion --jq '.conclusion')" = "action_required" ]; then
+ gh api -X POST "repos/$GITHUB_REPOSITORY/actions/runs/$ci_run/approve"
+ fi
gh run watch "$ci_run" --exit-status --interval 30
state="$(gh api "repos/$GITHUB_REPOSITORY/commits/$sha/check-runs?check_name=CI%20gate" \
--jq '(.check_runs | max_by(.id)) | if .status == "completed" then .conclusion else (.status // "missing") end')"
[ "$state" = "success" ] || { echo "::error::Candidate CI gate is $state."; exit 1; }
- # A concurrent main update rejects this ordinary fast-forward push.
- # No tag or publishing workflow is created when landing fails.
- git push origin HEAD:main
- git tag -a "v$V" -m "v$V"
- git push origin "v$V"
+ gh pr merge "$candidate" --merge --match-head-commit "$sha"
+ if [ "$TOKEN_IS_BOT" = "true" ]; then
+ gh workflow run ci.yml --ref main -f full=true -f include_macos=false
+ fi
+ - name: Tag the admitted release
+ env:
+ V: ${{ steps.bump.outputs.version || steps.resume.outputs.version }}
+ run: |
+ sha="$(git rev-parse HEAD)"
+ python scripts/ci/release_admit.py --tag "v$V" --sha "$sha" --repo "$GITHUB_REPOSITORY"
+ git config user.name "jarvis-release[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ if git show-ref --verify --quiet "refs/tags/v$V"; then
+ [ "$(git rev-parse "v$V^{}")" = "$sha" ] || { echo "::error::The tag already names another commit."; exit 1; }
+ else
+ git tag -a "v$V" -m "v$V"
+ git push origin "v$V"
+ fi
- name: Dispatch the publishing workflows on the tag
env:
- V: ${{ steps.bump.outputs.version }}
+ V: ${{ steps.bump.outputs.version || steps.resume.outputs.version }}
run: |
for wf in release.yml desktop-installers.yml sign-installer.yml; do
gh workflow run "$wf" --ref "v$V"
diff --git a/docs/ci-pipeline.md b/docs/ci-pipeline.md
index f05c49d69f..0d22ece25d 100644
--- a/docs/ci-pipeline.md
+++ b/docs/ci-pipeline.md
@@ -110,10 +110,16 @@ A release happens **only** when the maintainer asks for one.
`pyproject.toml`, `jarvis/__init__.py` and `uv.lock`, moves the `[Unreleased]` notes (or
the Conventional Commits since the last tag) into a dated CHANGELOG section
(`scripts/ci/cut_release.py`), and commits on a unique candidate branch.
- It dispatches full CI for that exact commit, waits for success, then
- fast-forwards protected main, tags, and dispatches the three publishing
- workflows on the tag. A failed check or concurrent main update prevents
- tagging and publication; no branch-protection bypass is needed.
+ It opens a candidate PR, waits for its `pull_request` CI, merges normally,
+ tags the admitted version commit, and dispatches the publishing workflows.
+ GitHub does not count `workflow_dispatch` job checks toward protected-branch
+ requirements ([GitHub documentation](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks#checks-from-some-workflow-jobs-are-not-evaluated)).
+ When repository policy blocks bot-created PRs, the workflow prints the
+ candidate compare link for a maintainer to open; an optional existing
+ `INTEGRATION_TOKEN` follows the merge train's token convention.
+ The optional `resume_sha` input finishes an already merged version commit
+ after an interrupted cut. It requires a full SHA on main, the current version,
+ and successful release admission; it cannot move an existing tag.
* **`release-gate.yml`** is the first job of `release.yml` (PyPI),
`desktop-installers.yml` and `sign-installer.yml`. It admits a tag only
when tag, versions and CHANGELOG agree, the commit is on main, and
diff --git a/tests/unit/ci/test_release_cut_workflow.py b/tests/unit/ci/test_release_cut_workflow.py
index 61de3b5f8e..c7a5d82930 100644
--- a/tests/unit/ci/test_release_cut_workflow.py
+++ b/tests/unit/ci/test_release_cut_workflow.py
@@ -1,4 +1,4 @@
-"""Exercise the release shell against fake Git/GitHub commands, without publishing."""
+"""Exercise release shell boundaries without a repository, credentials or network."""
from __future__ import annotations
@@ -12,64 +12,64 @@ import yaml
from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
-
- "watch_exit,gate_state,land_exit,success",
- [
- (0, "success", 0, True),
- (1, "failure", 0, False),
- (0, "in_progress", 0, False),
- (0, "success", 1, False),
- ],
-)
-def test_only_a_green_candidate_can_land_and_publish(
- tmp_path: Path,
- watch_exit: int,
- gate_state: str,
- land_exit: int,
- success: bool,
-) -> None:
- bash = shutil.which("bash")
- if os.name == "nt":
- # System32/bash.exe enters WSL, which does not preserve this test's
- # Windows environment or paths. Use the runner's Git Bash instead.
- git = shutil.which("git")
- roots = (Path(git).parent, Path(git).parent.parent / "bin") if git else ()
- bash = next(
- (str(root / "bash.exe") for root in roots if (root / "bash.exe").is_file()), None
- )
- if bash is None:
- pytest.skip("the workflow shell requires Bash")
- root = Path(__file__).resolve().parents[3]
- workflow = yaml.safe_load((root / ".github/workflows/release-cut.yml").read_text("utf-8"))
- step = next(
- step
- for step in workflow["jobs"]["cut"]["steps"]
- if step.get("name") == "Check the version commit before landing and tagging"
- )
- trace = tmp_path / "commands.txt"
- # Functions shadow commands only inside this disposable shell. No real
- # repository, credentials, GitHub API, or release is touched by this test.
- fakes = r"""
+_SHA = "1" * 40
+_FAKES = r"""
git() {
printf 'git %s\n' "$*" >> "$TRACE_FILE"
- if [ "$1" = rev-parse ]; then printf '%040d\n' 1; fi
- if [ "$1 $2 $3" = 'push origin HEAD:main' ]; then return "$LAND_EXIT"; fi
+ case "$1" in
+ rev-parse)
+ if [ "$2" = HEAD ]; then printf '%s\n' "$FAKE_SHA";
+ else printf '%s\n' "$TAG_SHA"; fi ;;
+ merge-base) return "$ANCESTOR_EXIT" ;;
+ show-ref) return "$TAG_EXISTS" ;;
+ checkout) : > checked-out ;;
+ esac
return 0
}
gh() {
printf 'gh %s\n' "$*" >> "$TRACE_FILE"
case "$1 $2" in
+ 'pr create') printf 'https://github.com/example/project/pull/1\n' ;;
+ 'pr merge') return "$LAND_EXIT" ;;
'workflow run') return 0 ;;
'run list') printf '123\n' ;;
+ 'run view') printf '\n' ;;
'run watch') return "$WATCH_EXIT" ;;
api\ *) printf '%s\n' "$GATE_STATE" ;;
*) return 2 ;;
esac
}
+python() {
+ printf 'python %s\n' "$*" >> "$TRACE_FILE"
+ if [ "$1" = -c ]; then
+ if [ -f checked-out ]; then printf '%s\n' "$RESUME_VERSION";
+ else printf '%s\n' "$BASE_VERSION"; fi
+ else return "$ADMIT_EXIT"; fi
+}
"""
+
+
+def _exercise(tmp_path: Path, step_names: list[str], **overrides: str):
+ bash = shutil.which("bash")
+ if os.name == "nt":
+ # System32/bash.exe enters WSL instead of the runner's Windows shell.
+ git = shutil.which("git")
+ roots = (Path(git).parent, Path(git).parent.parent / "bin") if git else ()
+ bash = next(
+ (str(root / "bash.exe") for root in roots if (root / "bash.exe").is_file()), None
+ )
+ if bash is None:
+ pytest.skip("the workflow shell requires Bash")
+ root = Path(__file__).resolve().parents[3]
+ workflow = yaml.safe_load((root / ".github/workflows/release-cut.yml").read_text("utf-8"))
+ steps = {step.get("name"): step for step in workflow["jobs"]["cut"]["steps"]}
+ trace = tmp_path / "commands.txt"
script = tmp_path / "release-test.sh"
- script.write_text(fakes + step["run"], encoding="utf-8", newline="\n")
+ script.write_text(
+ _FAKES + "\n".join(steps[name]["run"] for name in step_names),
+ encoding="utf-8",
+ newline="\n",
+ )
result = subprocess.run(
[bash, "--noprofile", "--norc", "-e", "-o", "pipefail", script.name],
cwd=tmp_path,
@@ -77,13 +77,27 @@ gh() {
**os.environ,
"V": "1.2.3",
"GITHUB_RUN_ID": "77",
+ "GITHUB_RUN_ATTEMPT": "2",
"GITHUB_REPOSITORY": "example/project",
"TRACE_FILE": trace.name,
+ "GITHUB_OUTPUT": "outputs.txt",
+ "GITHUB_STEP_SUMMARY": "summary.txt",
+ "RUNNER_TEMP": ".",
"PATH": "",
"BASH_ENV": "/dev/null",
- "WATCH_EXIT": str(watch_exit),
- "GATE_STATE": gate_state,
- "LAND_EXIT": str(land_exit),
+ "TOKEN_IS_BOT": "true",
+ "WATCH_EXIT": "0",
+ "GATE_STATE": "success",
+ "LAND_EXIT": "0",
+ "ADMIT_EXIT": "0",
+ "ANCESTOR_EXIT": "0",
+ "FAKE_SHA": _SHA,
+ "RESUME_SHA": _SHA,
+ "BASE_VERSION": "1.2.3",
+ "RESUME_VERSION": "1.2.3",
+ "TAG_EXISTS": "1",
+ "TAG_SHA": _SHA,
+ **overrides,
},
capture_output=True,
text=True,
@@ -91,20 +105,72 @@ gh() {
timeout=15,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
- assert trace.exists(), result.stdout + result.stderr
- commands = trace.read_text("utf-8").splitlines()
+ commands = trace.read_text("utf-8").splitlines() if trace.exists() else []
+ return result, commands
+
+
+ "overrides,success",
+ [
+ ({}, True),
+ ({"WATCH_EXIT": "1"}, False),
+ ({"GATE_STATE": "in_progress"}, False),
+ ({"LAND_EXIT": "1"}, False),
+ ({"ADMIT_EXIT": "1"}, False),
+ ],
+)
+def test_only_a_green_candidate_can_land_and_publish(tmp_path, overrides, success):
+ result, commands = _exercise(
+ tmp_path,
+ [
+ "Check the version commit before landing and tagging",
+ "Tag the admitted release",
+ ],
+ **overrides,
+ )
assert (result.returncode == 0) is success, result.stdout + result.stderr
- candidate = "git push origin HEAD:refs/heads/release-cut/v1.2.3-77"
+ candidate = "git push origin HEAD:refs/heads/release-cut/v1.2.3-77-2"
watch = "gh run watch 123 --exit-status --interval 30"
+ merge = f"gh pr merge release-cut/v1.2.3-77-2 --merge --match-head-commit {_SHA}"
assert commands.index(candidate) < commands.index(watch)
- if watch_exit or gate_state != "success":
- assert "git push origin HEAD:main" not in commands
+ assert any("--event pull_request" in command for command in commands)
+ assert "git push origin HEAD:main" not in commands
+ if overrides.get("WATCH_EXIT") or overrides.get("GATE_STATE"):
+ assert merge not in commands
+ if success:
+ assert commands.index(watch) < commands.index(merge)
+ assert commands.index(merge) < commands.index("git tag -a v1.2.3 -m v1.2.3")
+ assert commands[-1] == "git push origin v1.2.3"
+ else:
+ assert not any(command.startswith("git tag ") for command in commands)
+
+
+ "overrides,success",
+ [
+ ({}, True),
+ ({"RESUME_SHA": "refs/heads/unmerged"}, False),
+ ({"ANCESTOR_EXIT": "1"}, False),
+ ({"RESUME_VERSION": "1.2.2"}, False),
+ ({"ADMIT_EXIT": "1"}, False),
+ ({"TAG_EXISTS": "0", "TAG_SHA": "2" * 40}, False),
+ ],
+)
+def test_resume_requires_merged_current_version_and_admission(tmp_path, overrides, success):
+ result, commands = _exercise(
+ tmp_path,
+ [
+ "Select an already merged version commit",
+ "Tag the admitted release",
+ ],
+ **overrides,
+ )
+ assert (result.returncode == 0) is success, result.stdout + result.stderr
+ if overrides.get("ANCESTOR_EXIT") or overrides.get("RESUME_SHA"):
+ assert not any(command.startswith("git checkout ") for command in commands)
if success:
- assert commands.index(watch) < commands.index("git push origin HEAD:main")
- assert commands.index("git push origin HEAD:main") < commands.index(
- "git tag -a v1.2.3 -m v1.2.3"
- )
assert commands[-1] == "git push origin v1.2.3"
+ assert (tmp_path / "outputs.txt").read_text("utf-8") == "version=1.2.3\n"
else:
assert not any(command.startswith("git tag ") for command in commands)
assert "git push origin v1.2.3" not in commands