From cfdd45725b5686b14587514a829854c30051a8cc Mon Sep 17 00:00:00 2001 From: Thang Nguyen Date: Fri, 13 Nov 2026 16:48:32 +0700 Subject: [PATCH 1/3] feat: release notes generated from the app CHANGELOG at each release --- .github/workflows/release-notes.yml | 76 ++++++++++++++++++ .mintignore | 3 + README.md | 6 +- docs.json | 11 +++ release-notes.mdx | 119 ++++++++++++++++++++++++++++ scripts/gen_release_notes.py | 95 ++++++++++++++++++++++ 6 files changed, 309 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/release-notes.yml create mode 100644 release-notes.mdx create mode 100644 scripts/gen_release_notes.py diff --git a/.github/workflows/release-notes.yml b/.github/workflows/release-notes.yml new file mode 100644 index 0000000..26db31f --- /dev/null +++ b/.github/workflows/release-notes.yml @@ -0,0 +1,76 @@ +name: Release notes + +# Regenerates release-notes.mdx from the YourSSH CHANGELOG.md at the latest +# release, checks the build and links, pushes the page to main and deploys. +# Runs every six hours, on demand, or when the app's release workflow sends a +# `yourssh-release` repository_dispatch. +# +# The organisation doesn't let GitHub Actions open pull requests, so this job +# validates the site itself and pushes to main directly; the "Protect Main" +# ruleset lets only GitHub Actions bypass the pull-request requirement. +on: + schedule: + - cron: "23 */6 * * *" + workflow_dispatch: + repository_dispatch: + types: [yourssh-release] + +permissions: + contents: write + actions: write + +concurrency: + group: release-notes + cancel-in-progress: false + +jobs: + update: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Generate from the latest release's CHANGELOG + id: gen + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + tag=$(gh api repos/YoursshLabs/yourssh/releases/latest --jq .tag_name) + if ! [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "::error::Unexpected release tag: $tag"; exit 1 + fi + gh api "repos/YoursshLabs/yourssh/contents/CHANGELOG.md?ref=${tag}" --jq .content | base64 -d > "$RUNNER_TEMP/CHANGELOG.md" + python3 scripts/gen_release_notes.py "$RUNNER_TEMP/CHANGELOG.md" release-notes.mdx + if git diff --quiet -- release-notes.mdx; then + echo "Release notes already match $tag" + echo "changed=false" >> "$GITHUB_OUTPUT" + else + echo "changed=true" >> "$GITHUB_OUTPUT" + fi + echo "tag=$tag" >> "$GITHUB_OUTPUT" + + - name: Validate the site + if: steps.gen.outputs.changed == 'true' + run: | + npm i -g mint + mint validate + mint broken-links + + - name: Push to main and deploy + if: steps.gen.outputs.changed == 'true' + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ steps.gen.outputs.tag }} + run: | + set -euo pipefail + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add release-notes.mdx + git commit -m "docs: release notes for ${TAG}" + git push origin HEAD:main + # A push made with GITHUB_TOKEN doesn't start other workflows, so + # run the docs workflow on main explicitly to deploy. + gh workflow run docs.yml --ref main diff --git a/.mintignore b/.mintignore index 314d0ae..7b39af8 100644 --- a/.mintignore +++ b/.mintignore @@ -8,3 +8,6 @@ drafts/ # Task notes for maintainers (not published) .docs/ + +# Maintainer scripts (not published) +scripts/ diff --git a/README.md b/README.md index 98a2f6a..40704fe 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ Requires Node.js 20.17 or newer. Writing rules and terminology: [AGENTS.md](AGENTS.md). +## Release notes + +`release-notes.mdx` is generated by `scripts/gen_release_notes.py` from the app's `CHANGELOG.md` at the latest release (0.2.0 and later). `.github/workflows/release-notes.yml` runs every six hours, on demand, or on a `yourssh-release` repository dispatch from the app's release workflow: it regenerates the page, runs `mint validate` and `mint broken-links`, pushes it to `main` and starts the deployment. Don't edit the page by hand; fix the CHANGELOG instead. + ## Build and deploy `.github/workflows/docs.yml`: @@ -33,6 +37,6 @@ Writing rules and terminology: [AGENTS.md](AGENTS.md). - Every pull request and every push to `main` run `mint validate` and `mint broken-links`. - After those pass on `main`, the workflow asks Mintlify to deploy the site and waits for the result. It uses the repository secrets `MINTLIFY_API_KEY` (an admin API key, `mint_…`) and `MINTLIFY_PROJECT_ID`, both from the Mintlify dashboard's API keys page. Without them the deploy step is skipped with a warning. -`main` is protected: changes land through pull requests, and the **Build and check** job must pass before merging. +`main` is protected: changes land through pull requests, and the **Build and check** job must pass before merging. Only GitHub Actions may push directly, which the release-notes workflow uses after validating the site itself. The Mintlify GitHub App also deploys on every push to `main`. To make CI the only way the site deploys, turn off automatic deployments for this repository in the Mintlify dashboard. diff --git a/docs.json b/docs.json index 719970e..b3437fc 100644 --- a/docs.json +++ b/docs.json @@ -104,6 +104,17 @@ ] } ] + }, + { + "tab": "Release notes", + "groups": [ + { + "group": "Releases", + "pages": [ + "release-notes" + ] + } + ] } ], "global": { diff --git a/release-notes.mdx b/release-notes.mdx new file mode 100644 index 0000000..4df3e29 --- /dev/null +++ b/release-notes.mdx @@ -0,0 +1,119 @@ +--- +title: "Release notes" +description: "What changed in each YourSSH release." +icon: "newspaper" +--- + +{/* Generated by scripts/gen_release_notes.py from the YourSSH CHANGELOG.md at the latest release. Do not edit by hand. */} + +Download any release from the [releases page](https://github.com/YoursshLabs/yourssh/releases). The full history, including early development builds, is in [CHANGELOG.md](https://github.com/YoursshLabs/yourssh/blob/master/CHANGELOG.md). + + + +A new look (forui "Amber Brand" design system on desktop and mobile), a `yourssh` command-line client with `yourssh://` links, and a round of fixes found by driving the finished app end to end. + +### Added +- **`yourssh` command-line client (phase 1, macOS, Linux and Windows, run from source)** — `yourssh connect `, `ls [--json] [--tag T] [--filter Q]`, `version`, `open ` and `help` talk to the running app (NDJSON protocol v1) and start the app if it is not running. Hosts resolve by id, label or `user@host[:port]`; ad-hoc `user@host[:port]` works from the CLI only and signs in with the SSH agent's keys (a password-only server needs a saved host). `yourssh version` never starts the app. A debug build of the app uses its own endpoint (`YourSSH-dev`, `\\.\pipe\yourssh-cli-dev-`); the CLI reaches it with `YOURSSH_DEV=1`. macOS/Linux: a per-user Unix socket, 0600 in a 0700 run dir, that checks the peer uid. Windows: the named pipe `\\.\pipe\yourssh-cli-` with a current-user-only DACL and remote clients rejected; the app drops clients running as another user, and the CLI checks the pipe's server the same way before sending anything (a pipe owned by another user exits 4). Every request carries a token rotated at every launch, and the app is single-instance on all three (a second launch, including a clicked link, is handed to the running app before it starts anything else). Exit codes: 0 ok, 1 error, 2 usage, 3 app unreachable, 4 denied. Not yet: packaging the CLI binary in releases (today `yourssh` in a release is the GUI app) and an install button, `sftp`/`tunnel`/`import`/`export`, MCP. +- **`yourssh://connect/` links** — open a saved host from a browser or script; saved hosts only, repeats of the same link within 2 s are ignored, and a refused link (unknown host, unsupported form) is listed in the notification bell. The scheme is registered by the macOS app, the Windows installer (current user) and the Linux .deb; the portable zip and tarball do not register it. +- **Audit source for CLI and URL connects** — SSH connect rows carry `meta.source` = `cli` / `url`; RDP and VNC rows keep `source: rdp|vnc` and carry `via` = `cli` / `url`. + +### Fixed +- A new SSH session shows a single prompt; the prompt printed before the invisible shell-integration setup no longer stays behind as an empty line. +- **Snippets no longer disappear after allowing the bundled "Snippets" plugin.** Earlier builds shipped a half-migrated script copy of Snippets that moved your snippets out of the built-in plugin's storage on first load and then failed, so the next launch showed only the defaults. The script copy is no longer installed, a leftover copy in `~/.yourssh/plugins/snippets` is ignored (script plugins can't reuse a built-in plugin's id), and the moved snippets are restored once at startup (merged, no duplicates). +- Bulk "Run command" no longer reports `exit -1` for fast commands: the SSH layer kept an exit status that arrived before the session was ready. The footer counts non-zero exits separately (`N ok · M non-zero exit · K failed`) and an unknown exit status is shown as such. +- A host whose name doesn't resolve no longer sits on "Connecting…" forever: the TCP dial times out after 15 s and the connecting screen shows the last error with the retry attempt. +- Entering RDP/VNC fullscreen no longer raises a framework error; the first RDP connect shows a neutral "verifying certificate" state behind the trust dialog instead of an error with Retry; Retry buttons have a normal width. +- Shell-integration gutter markers follow their prompt line and disappear on `clear` instead of floating on empty rows. +- Field errors in the host editor and port-forward editor clear as soon as the value is fixed, and the port error fits on one line. +- The hosts toolbar fits the 900×600 minimum window (lower-priority controls collapse into a menu); the Mail Catcher and AI chat titles no longer truncate with room to spare; multi-line Web Tools editors start at the top; the mobile Generate/Import key sheets have an opaque surface; Esc closes the LAN-sync QR dialog. +- SFTP shows readable errors (e.g. '"releases" already exists') instead of raw `SftpStatusError` codes when creating or renaming. +- An empty split pane explains how to fill it; remaining all-caps buttons and titles (Keychain, Port forwarding, Audit log, bulk dialogs) use sentence case. +- **The host editor no longer leaks one host's form into another.** Opening "Edit" on a second host (or "New host" / "Duplicate") while the editor was open kept the first host's fields, and Save wrote them (including the password) into the second host. +- The terminal header and status bar follow edits to the host (label, user, tags, jump chain) instead of showing the values from when the tab was opened. +- Mail catcher: messages whose log starts with ESMTP options (`mail options: ['BODY=8BITMIME']`) are no longer dropped; the body is parsed separately from the headers, *Clear all* persists, and the log is written unbuffered in append mode. +- Port validation ("Invalid (1–65535)") in both host editors (SSH/RDP/VNC port and proxy port), port forwarding and the Cloudflare tunnel panel; an empty port keeps its default. +- Deleting a host also removes its stored proxy password. +- The mobile sync code and anonymous key are hidden behind a reveal toggle. +- The status bar also shows in RDP and VNC sessions. +- Terminal search and input bars keep or return focus correctly (Esc, Enter, clicking away). +- The read-only "Watching" banner has its own informational colour again. +- Session and DevOps result tabs can be selected and closed from the keyboard (Tab to a tab, Enter/Space to select, Tab again to its close button). +- List items in bottom sheets on mobile are at least 44 px tall. +- The Cloudflare tunnel panel shows "Required" / "Invalid (1–65535)" for a missing label or a bad port instead of silently adding nothing or falling back to 3000 (an empty port still means 3000). + +### Changed +- **New confirmations:** clearing captured mail in the Mail Catcher, deleting a host from the dashboard card menu, removing a Known Hosts entry (its pinned key), Sync *Disconnect*, Docker Compose *Down* and opening an executable file externally now ask first; the safe choice has default focus. +- **SFTP click model:** on both panels a single click selects, and double-click or Enter opens. +- **Host editor:** a *Delete* button was added to the footer and the *CONNECT* button was removed. +- **AI chat:** Enter sends, Shift+Enter inserts a new line. +- **New look:** the app moves to the Amber Brand palette (warm dark surfaces, amber accent), the Inter font and a forui-based UI foundation on desktop and mobile. +- **New "YourSSH Amber" terminal theme**, the default for new installs. Existing installs keep their current terminal theme. +- Built with Flutter 3.50. +- **New sidebar** with grouped sections and an amber selected item. +- **New tab bar** for sessions, with the active tab marked in amber. +- **New toasts** for notifications, shown bottom-right on desktop. +- **UI clean-up:** a lint gate (`tool/check_ui_lint.sh`, run in PR CI) keeps Material `IconButton`/`AlertDialog`/`SnackBar`/`Icons`/`ScaffoldMessenger` out of the app and the plugin packages, remaining colour literals moved to tokens, the discovery and server-monitor sheets and the inline tab rename / fallback code editor fields moved to forui, the gate also rejecting `showDialog(`, `showModalBottomSheet` and `TextField(`, and `AppColors`/`MobileColors` are now `@Deprecated` aliases of the new tokens (kept rather than deleted, to avoid churn across ~460 call sites). +- **New dialogs** across the app; security prompts (host key, RDP certificate) now focus the safe choice by default. + + + + + +### Performance +- **Terminal output is ~10× faster and never freezes the UI** — measured with vtebench-style corpora in a local shell (121×40, macOS): 40 MB of plain log output now takes 0.35 s (was ≈3.7 s with the window frozen), 20 MB of colored output 0.26 s, 8 MB of Unicode 0.13 s and 15 MB of full-screen TUI redraws 0.15 s — on par with Ghostty and 5–9× faster than Termius. During a flood the terminal keeps repainting at ~55 fps with no frame over 16.7 ms, and Ctrl+C stops the output in ~25 ms instead of letting a queued backlog print for seconds. + - Parser rewrite in the xterm fork (≈10× faster: bulk text runs, no per-chunk allocation, memoized accent composition, scrollback line reuse) with a byte entry point, so output goes from the PTY/SSH channel to the parser without string round-trips. + - Output is parsed in short time slices with repaints throttled to the display, with credit-based flow control on local PTYs (2 MiB window) and SSH (channel pause/resume) so the app never builds an unbounded backlog. + - New glyph-atlas renderer: each glyph is rasterized once and drawn from a GPU texture, cutting a full-screen frame from ~10 ms to ~2 ms; complex cells (emoji, underline, combining marks) keep the previous path. Pixel output matches the old renderer. + - DEC mode 2026 (synchronized output) for flicker-free full-screen redraws. + +### Security +- **SSH agent forwarding:** forwarded agent channels are accepted only after the server accepted this client's forwarding request; the Keychain fallback serves only the host's own key; only identity-list and sign requests are relayed. +- **SSH transport hardening:** bounded agent frames, channel window enforcement, malformed packets fail the connection instead of hanging it, and Diffie-Hellman group-exchange parameters are validated. +- **Remote-controlled resource limits:** terminal window-resize requests are ignored, repeat counts and escape-sequence lengths are capped, RDP/VNC desktop sizes are capped at 8192 px per edge, and server clipboard text is capped at 1 MiB with a new per-host *Accept remote clipboard* switch (on by default). +- **Files:** Windows *Open with* no longer goes through the command shell; *Open externally* refuses executable file types downloaded from a server; temporary copies live in private, random folders that are removed afterwards; generated keys are private before any key material is written and never overwrite an existing key; the sudo SFTP helper path must be a known `sftp-server`. +- **Remote helpers:** kubectl arguments are shell-quoted and port-forwards bind to localhost on the remote host; MCP gateway / Cloudflare tunnel / mail catcher are stopped by PID with private temp files; HTTP/SOCKS proxy handshakes are size-limited; LAN (P2P) sync binds only the chosen interface and caps the transfer. +- **JS plugins:** per-call time limits plus memory and stack caps, misbehaving plugins are unloaded, consent is tied to the plugin's file contents, `terminal.read` can no longer rewrite output, and plugin paths can't escape the plugin folder. +- **Storage:** AI and S3 keys use the same macOS Keychain mode as host passwords, the Gemini key is sent in a header instead of the URL, recordings and the audit database are readable only by the user, and Android app backups are disabled. + +### Fixed +- Terminal: no more exceptions from truncated color sequences or `ESC[1K`/`ESC[1J` at column 0; scrolling inside a scroll region and resizing after the scrollback filled up no longer corrupt the buffer (covered by a 50,000-case fuzz test). +- `.bin` files can be opened externally on Linux again. +- Code editor saves on Android no longer wrap the file in quotes. +- Local shell: a failed `execvp` no longer leaves a duplicate process; Windows command lines are quoted correctly and support non-ASCII paths. +- Mail catcher works on Python 3.12+ (falls back to `aiosmtpd`). + + + + + +### Security +- **Cloud sync no longer exposes the sync code** — the Supabase row id was the sync code itself, which is also the only key-derivation input, so anyone holding the project's anon key could list `sync_data` and decrypt every row, saved host passwords included. Rows are now keyed by a one-way SHA-256 of the code (the code never reaches the server); existing rows are read once from the legacy id and moved on the next push. Pull also requires the payload's authenticated inner timestamp to be newer than the last push/apply, so a replayed old ciphertext can no longer roll the host list back. Devices still on an older version keep using the legacy row until they update. +- **Terminal sharing is end-to-end encrypted and only the controlling guest can type** — the host applied every `input` event it received, and the channel was a public, plaintext broadcast keyed by a guessable 6-character code. Share codes are now `XXXXXX-XXXXXXXXXXXXXXXX` (80-bit secret), the channel name is a hash of the code, every message is an AES-256-GCM envelope, and input is applied only from the guest currently granted control. Old and new versions cannot share with each other. +- **SSH host-key pinning can no longer be bypassed by switching key type** — a server presenting a new host-key algorithm for a host already pinned under another type was trusted silently; it now raises the host-key dialog ("Host key type changed"). **Test connection** also verifies the target and every jump host instead of accepting any key, and fails closed when no verifier is available. +- **SFTP downloads cannot write outside the chosen folder** — server-supplied names such as `../x`, absolute paths or `a/..` are rejected (skipped in folder downloads, refused for single files, the external editor and the code editor); folder downloads stop at 64 levels so symlink loops can't recurse forever. +- **RDP asks before sending credentials to an unpinned server** — the first connect to a host without a pinned certificate sent the password (TLS mode) or an NTLM response (NLA) before the trust dialog appeared. The connection now stops before authentication, shows the certificate, and reconnects with the pin once you trust it. +- **JS plugin panels respect permissions** — panel messages handled natively (`ssh-exec`, `ssh-sessions`, `sftp-list`, `sftp-read`) skipped the permission check, so a plugin granted only `ui.panel` could run commands on every session. +- **macOS updates are signature-checked** — the downloaded installer must carry the YourSSH Developer ID signature (team `84T567KMYD`) before it is opened; the old quarantine-stripping step is gone. Release builds are now signed with that Developer ID and notarized by Apple. +- **Release pipeline hardening** — every GitHub Action is pinned to a commit SHA and the workflow token is read-only except for the final publish step. +- **Rust dependencies** — `rustls` 0.23.46, `rustls-webpki` 0.103.16, `h2` 0.4.20, `tokio` 1.54.1 and others bumped past published advisories. + +### Added +- **"YourSSH Dark" terminal theme** (catalog 44 → 45) — the app's own color scheme, first in the visual picker and the fallback an unknown theme name resolves to: a neutral charcoal base with a deliberately desaturated ANSI set so long log output stays flat and readable, and azure/teal accents on the cursor, selection, and current search hit. The stored default for existing and new installs is unchanged (Dracula). + +### Fixed +- **VNC did not work in release builds** — the release pipeline never built or bundled the VNC native library; it now ships on macOS, Windows and Linux. +- **SFTP mode "Sudo" was ignored, so browsing failed with `Permission denied (code 3)`** (#109) — every SFTP entry point is handed a `Host` snapshot captured when its panel/slot was created, and `openSftp` read the SFTP mode from that snapshot. Switching a host to Sudo/Custom afterwards therefore changed nothing: listings kept running through the plain `sftp` subsystem as the login user, with no sudo prompt and no `root` badge in the panel header (the dual-panel source picker also short-circuits when the same host is re-picked, so the snapshot never refreshed). `openSftp` now resolves the host by id at call time (`resolveSftpHost` + the `defaultHostLookup` wiring), which covers the panels, transfers, file operations, the editor, path autocomplete and mobile in one place, and the header badge reads the live host too +- **Local terminal tabs ignored the color theme** — `LocalTerminalPane` built xterm's `TerminalView` without a `theme:` argument, so every local shell rendered in xterm's built-in default palette and the Settings → Terminal color theme silently applied to SSH tabs only. The pane now resolves the global theme (local sessions have no host, so no per-host override applies). +- **Screenshot harness wrote two shots to stale paths** — the recording-library and audit-log captures went to `screenshots/09-recording/` and a flat `screenshots/audit-log.png`, neither of which the README reads, so those two images silently went stale while every run left untracked files behind. Both now write into `screenshots/10-audit-recording/` under the filenames the README references. The output root is also derived from the repo (walked up from the CWD) instead of one developer's absolute home path, and the run now fails if the README references a screenshot that is not on disk. + + + + + +### Added +- **Android app (development preview)** — YourSSH now targets Android as a focused mobile SSH client, sharing the platform-agnostic core with desktop. `main()` branches on `isMobilePlatform` and mounts a separate mobile UI, so no desktop code path changes. Hosts list with search / folder chips / tag grouping and live reachability probes; a `TerminalView` with an **accessory key bar** (sticky Ctrl/Alt, ^C/^D, arrows, special characters), pinch-to-zoom and long-press cursor drag; single-panel **SFTP** (browse / download / upload); **snippets** quick-run; **key** generation and import; **port forwarding** rules; host import from desktop over cloud Supabase pull or a **P2P QR camera scan**; biometric **app-lock** and the TOFU host-key dialog. The release ships an APK signed with the **debug key** — it installs and runs, but a real release keystore has to land before it can go to Play or be upgraded in place. RDP/VNC, plugins, recording and the audit log stay desktop-only. + +### Changed +- **New app icon** — the launcher artwork is redrawn from a vector master instead of hand-exported bitmaps: an amber squircle (superellipse corners) with a chunky `>_` prompt glyph that stays legible down to 16 px. `tool/gen_app_icons.py` regenerates every platform target from `assets/branding/*.svg` — macOS iconset (inset to Apple's 824/1024 grid), a 16–256 px Windows `.ico`, the Android adaptive layers (gradient background drawable, foreground inside the 66dp safe circle, plus an Android 13+ themed/monochrome layer), and the in-app / README logos. Measured: the glyph holds 6.4–12:1 contrast against the amber plate and the icon reads at 6.3–7.3:1 against every dark app surface. + + diff --git a/scripts/gen_release_notes.py b/scripts/gen_release_notes.py new file mode 100644 index 0000000..e506236 --- /dev/null +++ b/scripts/gen_release_notes.py @@ -0,0 +1,95 @@ +#!/usr/bin/env python3 +"""Generate release-notes.mdx from the YourSSH CHANGELOG.md. + +Usage: gen_release_notes.py CHANGELOG.md release-notes.mdx [--since 0.2.0] + +Each "## [x.y.z] — date" section becomes a Mintlify block. Text +outside code spans/fences is escaped for MDX ({ } < become literals), so +CHANGELOG prose can never break the docs build. Sections before --since are +left out (the early 0.1.x entries are development notes). +""" +import re +import sys + +HEAD = re.compile(r"^## \[(\d+\.\d+\.\d+)\]\s*[—-]\s*(\d{4}-\d{2}-\d{2})\s*$") + + +def ver(v): + return tuple(int(x) for x in v.split(".")) + + +def escape_line(line): + # Escape MDX-significant characters outside inline code spans. + parts = re.split(r"(`+[^`]*`+)", line) + out = [] + for i, p in enumerate(parts): + if i % 2 == 1: + out.append(p) + else: + out.append(p.replace("{", "\\{").replace("}", "\\}").replace("<", "<")) + return "".join(out) + + +def convert(text, since): + sections, cur = [], None + for line in text.splitlines(): + m = HEAD.match(line) + if m: + cur = {"version": m.group(1), "date": m.group(2), "lines": []} + sections.append(cur) + continue + if line.startswith("## "): # [Unreleased] or anything else ends a section + cur = None + continue + if cur is not None: + cur["lines"].append(line) + sections = [s for s in sections if ver(s["version"]) >= ver(since)] + body = [] + for s in sections: + lines = s["lines"] + while lines and lines[-1].strip() in ("", "---"): + lines.pop() + while lines and not lines[0].strip(): + lines.pop(0) + fenced = False + conv = [] + for l in lines: + if l.lstrip().startswith("```"): + fenced = not fenced + conv.append(l) + continue + conv.append(l if fenced else escape_line(l)) + body.append( + f'\n\n' + + "\n".join(conv) + + "\n\n\n" + ) + header = ( + "---\n" + 'title: "Release notes"\n' + 'description: "What changed in each YourSSH release."\n' + 'icon: "newspaper"\n' + "---\n\n" + "{/* Generated by scripts/gen_release_notes.py from the YourSSH CHANGELOG.md at the latest release. Do not edit by hand. */}\n\n" + "Download any release from the [releases page](https://github.com/YoursshLabs/yourssh/releases). " + "The full history, including early development builds, is in [CHANGELOG.md](https://github.com/YoursshLabs/yourssh/blob/master/CHANGELOG.md).\n\n" + ) + return header + "\n".join(body) + + +def main(): + args = sys.argv[1:] + since = "0.2.0" + if "--since" in args: + i = args.index("--since") + since = args[i + 1] + del args[i : i + 2] + src, dst = args + with open(src, encoding="utf-8") as f: + out = convert(f.read(), since) + with open(dst, "w", encoding="utf-8") as f: + f.write(out) + + +if __name__ == "__main__": + main() From d97bbf1c6c1d05e0936cb6bf491da3f5b78bcaba Mon Sep 17 00:00:00 2001 From: Thang Nguyen Date: Fri, 13 Nov 2026 16:50:29 +0700 Subject: [PATCH 2/3] feat(release-notes): open a PR, check it and merge instead of pushing to main --- .github/workflows/release-notes.yml | 35 +++++++++++++++++++++++------ README.md | 4 ++-- 2 files changed, 30 insertions(+), 9 deletions(-) diff --git a/.github/workflows/release-notes.yml b/.github/workflows/release-notes.yml index 26db31f..94f8c07 100644 --- a/.github/workflows/release-notes.yml +++ b/.github/workflows/release-notes.yml @@ -5,9 +5,11 @@ name: Release notes # Runs every six hours, on demand, or when the app's release workflow sends a # `yourssh-release` repository_dispatch. # -# The organisation doesn't let GitHub Actions open pull requests, so this job -# validates the site itself and pushes to main directly; the "Protect Main" -# ruleset lets only GitHub Actions bypass the pull-request requirement. +# main is protected (pull request + a green "Build and check"), so the job +# opens a pull request, runs the docs workflow on it (a PR opened with +# GITHUB_TOKEN doesn't start workflows by itself), merges it once the check is +# green, then runs the docs workflow on main to deploy. Needs the organisation +# setting "Allow GitHub Actions to create and approve pull requests". on: schedule: - cron: "23 */6 * * *" @@ -17,6 +19,7 @@ on: permissions: contents: write + pull-requests: write actions: write concurrency: @@ -59,18 +62,36 @@ jobs: mint validate mint broken-links - - name: Push to main and deploy + - name: Open the pull request, check it, merge and deploy if: steps.gen.outputs.changed == 'true' env: GH_TOKEN: ${{ github.token }} TAG: ${{ steps.gen.outputs.tag }} run: | set -euo pipefail + branch="release-notes/${TAG}" git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git switch -c "$branch" git add release-notes.mdx git commit -m "docs: release notes for ${TAG}" - git push origin HEAD:main - # A push made with GITHUB_TOKEN doesn't start other workflows, so - # run the docs workflow on main explicitly to deploy. + git push --force origin "$branch" + sha=$(git rev-parse HEAD) + if ! gh pr view "$branch" --json number >/dev/null 2>&1; then + gh pr create --base main --head "$branch" \ + --title "docs: release notes for ${TAG}" \ + --body "Generated from the YourSSH CHANGELOG at ${TAG} by the release-notes workflow." + fi + # Produce the required "Build and check" status on the PR head. + gh workflow run docs.yml --ref "$branch" + run_id="" + for i in $(seq 1 30); do + sleep 10 + run_id=$(gh run list --workflow docs.yml --branch "$branch" --event workflow_dispatch \ + --json databaseId,headSha --jq "map(select(.headSha == \"$sha\")) | .[0].databaseId // empty") + [ -n "$run_id" ] && break + done + [ -n "$run_id" ] || { echo "::error::The docs check did not start"; exit 1; } + gh run watch "$run_id" --exit-status + gh pr merge "$branch" --merge --delete-branch gh workflow run docs.yml --ref main diff --git a/README.md b/README.md index 40704fe..76373c7 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Writing rules and terminology: [AGENTS.md](AGENTS.md). ## Release notes -`release-notes.mdx` is generated by `scripts/gen_release_notes.py` from the app's `CHANGELOG.md` at the latest release (0.2.0 and later). `.github/workflows/release-notes.yml` runs every six hours, on demand, or on a `yourssh-release` repository dispatch from the app's release workflow: it regenerates the page, runs `mint validate` and `mint broken-links`, pushes it to `main` and starts the deployment. Don't edit the page by hand; fix the CHANGELOG instead. +`release-notes.mdx` is generated by `scripts/gen_release_notes.py` from the app's `CHANGELOG.md` at the latest release (0.2.0 and later). `.github/workflows/release-notes.yml` runs every six hours, on demand, or on a `yourssh-release` repository dispatch from the app's release workflow: it regenerates the page, runs `mint validate` and `mint broken-links`, opens a pull request, runs **Build and check** on it, merges it and starts the deployment. Don't edit the page by hand; fix the CHANGELOG instead. ## Build and deploy @@ -37,6 +37,6 @@ Writing rules and terminology: [AGENTS.md](AGENTS.md). - Every pull request and every push to `main` run `mint validate` and `mint broken-links`. - After those pass on `main`, the workflow asks Mintlify to deploy the site and waits for the result. It uses the repository secrets `MINTLIFY_API_KEY` (an admin API key, `mint_…`) and `MINTLIFY_PROJECT_ID`, both from the Mintlify dashboard's API keys page. Without them the deploy step is skipped with a warning. -`main` is protected: changes land through pull requests, and the **Build and check** job must pass before merging. Only GitHub Actions may push directly, which the release-notes workflow uses after validating the site itself. +`main` is protected: changes land through pull requests, and the **Build and check** job must pass before merging. The Mintlify GitHub App also deploys on every push to `main`. To make CI the only way the site deploys, turn off automatic deployments for this repository in the Mintlify dashboard. From 57c182f7acfb7a28918eb371aa50fc8c25914206 Mon Sep 17 00:00:00 2001 From: Thang Nguyen Date: Fri, 13 Nov 2026 16:50:41 +0700 Subject: [PATCH 3/3] chore: header comment --- .github/workflows/release-notes.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release-notes.yml b/.github/workflows/release-notes.yml index 94f8c07..56d9445 100644 --- a/.github/workflows/release-notes.yml +++ b/.github/workflows/release-notes.yml @@ -1,7 +1,7 @@ name: Release notes # Regenerates release-notes.mdx from the YourSSH CHANGELOG.md at the latest -# release, checks the build and links, pushes the page to main and deploys. +# release, checks the build and links, lands it on main through a PR and deploys. # Runs every six hours, on demand, or when the app's release workflow sends a # `yourssh-release` repository_dispatch. #