automation: Docs update for OpenHands v1.22.0 release

Start with the Agent Canvas MCP health section, the Git Sync page, and the managing-automations page named in the checklist; compare each claim with the linked pull requests and human-testing notes. Update the confirmed v1.22.0 behavior, including cloud remote-MCP testing, stdio limitations, and Git Sync permissions, while checking the items marked for maintainer confirmation. Done means affected pages no longer contain stale claims and the documentation-needed items are resolved.

Release

• Version: v1.22.0
• Published: 2026-09-22T16:28:11Z
• URL: https://github.com/OpenHands/OpenHands/releases/tag/v1.22.0
• Prerelease: no

Release summary

OpenHands v1.22.0 contains three features, five bug fixes, one documentation change, and two maintenance items. The most user-visible feature lets cloud-backend users test remote MCP servers from the MCP settings page via the app server's new POST /api/v1/mcp/test endpoint. Git Sync is opened to organization admins/owners on cloud backends (previously local-backend-only). A third feature completes recently added Turkish UI translations. The fixes address the add-automation entry point for org members, base-path preservation for links that leave the Canvas SPA, sibling MCP server preservation when saving to a cloud backend, home automation row linking, and hiding cloud organizations the server marks is_visible=false. Maintenance bumps the default SDK/Agent Server/TypeScript client to 1.49.4 and Automation to 1.14.0.

Documentation review checklist

• feat: test remote MCP servers on cloud backends via the app server (PR #17276) — documentation needed. Remote (SSE/HTTP) MCP servers on cloud backends can now be tested/health-checked from the MCP settings page; the app server exposes POST /api/v1/mcp/test with the same contract as the local agent-server endpoint. stdio servers are still not testable on cloud backends because they spawn inside the sandbox, and the synthetic { ok: true, tools: [] } short-circuit is retained only for them. The Agent Canvas "Check MCP Server Health" section (/openhands/usage/agent-canvas/customize-and-settings#check-mcp-server-health) describes the health statuses but does not explain the cloud-vs-local testing behavior or why stdio servers show no Test button. Source: https://github.com/OpenHands/OpenHands/pull/17276
• feat: open Git Sync to org admins on cloud backends (PR #17216) — documentation needed. Git Sync is no longer restricted to local backends: the button follows org admin/owner (canManage) permissions, the page drops the local-only gate, and org members without permission see a no-access state. The Git Sync docs page (/openhands/usage/agent-canvas/git-sync) explicitly states "Git Sync is not available for cloud backends" and its troubleshooting table says to "Confirm the active backend is local", both of which are now stale. Recommend documenting org-admin/owner access and the member no-access state, and removing the local-only claim. Source: https://github.com/OpenHands/OpenHands/pull/17216
• feat(i18n): translate recently added Turkish UI strings (PR #17581) — probably no documentation change. Translates 70 user-facing strings into Turkish and corrects the Turkish SETTINGS value. This is a UI localization change with no documented behavior, feature, or configuration change. No docs update identified from the evidence. Source: https://github.com/OpenHands/OpenHands/pull/17581
• fix: show the add automation menu to org members (PR #17526) — documentation needed. The Automate list previously gated the add/import menu on manage_automations, hiding the entry point from org members. The Canvas half of the fix makes the menu follow the view permission. The managing-automations page (/openhands/usage/agent-canvas/managing-automations) documents manage-permission requirements for editing but does not state who can create an automation. The PR body notes a second (backend) half is still required; treat behavior as needing confirmation. Source: https://github.com/OpenHands/OpenHands/pull/17526
• fix(canvas): keep the base path on links that leave the app (PR #17617) — probably no documentation change. Fixes cmd/ctrl+click, middle-click, copied links, toast links, and exported records in the cloud deployment resolving to the enterprise app root instead of the Canvas mount (/canvas). This is a URL/routing correctness fix internal to the Canvas SPA; it does not change documented user procedures. Source: https://github.com/OpenHands/OpenHands/pull/17617
• fix: preserve sibling MCP servers when saving to a cloud backend (PR #17467) — needs maintainer confirmation. Saving a token-based MCP server from Canvas against a cloud backend previously dropped sibling MCP servers from the saved mcp_config map (a data-loss bug), which made conversations miss those servers while the MCP views still listed them. The fix changes the save payload in src/utils/mcp-config.ts / settings-service.api.ts. If any docs describe MCP configuration persistence on cloud backends, they may need a note; otherwise no user-facing procedure changed. Source: https://github.com/OpenHands/OpenHands/pull/17467
• fix: link home automation rows to the automation view (PR #17466) — probably no documentation change. Home-page Automations rows previously linked to the automation's latest run conversation, which other org members cannot read. Rows now link to the automation page. Behavior correction only; no documented procedure identified. Source: https://github.com/OpenHands/OpenHands/pull/17466
• fix(canvas): hide cloud orgs the server marks is_visible=false (PR #17624) — needs maintainer confirmation. Canvas now filters cloud organizations whose is_visible is false (derived from the backend HIDE_PERSONAL_WORKSPACES policy) out of the backend selector and related org consumers. If docs describe the cloud organization/backend selector or personal workspaces, they may need a note about hidden orgs; the Canvas org-selection docs were not found to reference this behavior. Source: https://github.com/OpenHands/OpenHands/pull/17624
• docs(review): add repository and product scope to the Canvas review guide (PR #17606) — probably no documentation change. Adds a repository/product scope section to .agents/skills/custom-codereview-guide.md in the OpenHands repository (an internal contributor/reviewer guide), not user-facing product documentation. Source: https://github.com/OpenHands/OpenHands/pull/17606
• chore: consume SDK 1.49.4 and Automation 1.14.0 (PR #17628) — needs maintainer confirmation. Bumps the default SDK, Agent Server, and TypeScript client to 1.49.4 and Automation to 1.14.0, and removes the obsolete agent-client-protocol<0.11 constraint. If docs reference specific default runtime versions or compatibility minimums, they may need updating; the only current docs version reference found is historical release-notes text. Source: https://github.com/OpenHands/OpenHands/pull/17628

Pull request review

• https://github.com/OpenHands/OpenHands/pull/17276 — Routes remote-server tests on cloud backends to the app server's POST /api/v1/mcp/test and narrows the cloud guards from "cloud" to "cloud and stdio"; changed files are Canvas src/api/**, src/components/features/mcp-page/**, and tests. Documentation impact: the Agent Canvas MCP health section should explain cloud remote testing and stdio test unavailability.
• https://github.com/OpenHands/OpenHands/pull/17216 — Git Sync button now follows canManage (org admins/owners), page shows a member no-access state, and cloud git-sync calls send standard headers; changed files are under src/routes, src/hooks, src/components/features/automations/git-sync, src/api/automation-service, and src/i18n. Documentation impact: the Git Sync page's explicit "not available for cloud backends" claim must be corrected. The PR notes a ship-order dependency on the Automation service and the Cloud chart change.
• https://github.com/OpenHands/OpenHands/pull/17581 — Single-file Turkish translation update (src/i18n/translation.json). No user-facing documentation impact found.
• https://github.com/OpenHands/OpenHands/pull/17526 — Makes the add/import automation menu visible to org members by changing use-automation-permissions.ts and automations-list.tsx. Documentation impact: the managing-automations page could clarify who can create automations; the PR body states the Canvas half requires a backend counterpart and was unit-tested rather than exercised against a live cloud backend.
• https://github.com/OpenHands/OpenHands/pull/17617 — Adds base-path-aware URL helpers and updates link/toast/export call sites under src/utils, src/components/shared, src/hooks, and src/services. Internal routing fix; no documented procedure changed.
• https://github.com/OpenHands/OpenHands/pull/17467 — Changes the cloud settings save payload so untouched MCP servers are preserved (src/api/settings-service/settings-service.api.ts, src/utils/mcp-config.ts, plus a specs/mcp-settings.md note). The author states the full add-two-servers flow was not exercised against a live cloud backend. Documentation impact is limited to any MCP cloud-persistence guidance.
• https://github.com/OpenHands/OpenHands/pull/17466 — Changes home-automation-activity.ts so home rows link to the automation view. Internal linking fix; no documented procedure changed.
• https://github.com/OpenHands/OpenHands/pull/17624 — Adds optional is_visible to the cloud org type and filters hidden orgs in use-cloud-organizations.ts, with tests. Documentation impact only if org-selector docs describe hidden/personal workspaces.
• https://github.com/OpenHands/OpenHands/pull/17606 — One documentation edit to an internal reviewer guide (.agents/skills/custom-codereview-guide.md). No user-facing documentation impact found.
• https://github.com/OpenHands/OpenHands/pull/17628 — Bumps version defaults across config/defaults.json, package.json, package-lock.json, scripts/dev-safe.mjs, scripts/check-sdk-version-sync.mjs, a workflow, and AGENTS.md; removes the agent-client-protocol<0.11 constraint. Documentation impact is limited to any docs referencing specific default runtime versions.

Human testing required

• Cloud remote-MCP testing (PR #17276): On a cloud backend serving POST /api/v1/mcp/test, open Settings > MCP with a remote (SSE/HTTP) server installed. Select Test connection and verify the status dot turns reachable with a tool count, or reports a timeout/connection/credential message with Retry. Edit the server with the credential left as ********** and verify the test still uses the stored value. Add or edit a stdio server and verify no Test button appears and no verdict is shown.
• Git Sync org-admin access (PR #17216): Requires a cloud backend running the org-scoped Git Sync change. Sign in as an org admin/owner, open /automations, verify the Git Sync button is present, save a repository config, and confirm the status card shows the repo. Sign in as a member and verify the button is absent and the Git Sync page shows the no-access state. Verify local-backend behavior is unchanged.
• Add-automation entry point for org members (PR #17526): On a cloud backend where a member lacks manage_automations but can view automations, open the Automate list and verify the add/import menu is visible. The PR body notes a separate backend change is required before this is fully effective end-to-end; verify the backend counterpart is deployed.
• Sibling MCP preservation on cloud save (PR #17467): With two or more MCP servers configured against a cloud backend, add or edit one token-based server and save. Verify the untouched servers remain configured and their stored credentials are preserved (not dropped from mcp_config), and that a new conversation still sees all servers.
• Hidden cloud organizations (PR #17624): On a deployment where the backend marks an organization (e.g. personal workspace) is_visible=false, open the backend/org selector and verify the hidden org is not offered, and that no /settings?org=<hidden> deep link is generated. Verify orgs without the field still appear.
• Runtime default versions (PR #17628): Confirm the intended default Agent Server/SDK/TypeScript client (1.49.4) and Automation (1.14.0) versions against the release's config/defaults.json, and check whether any published docs page references specific default runtime versions that now need updating.

Suggested documentation locations

• /openhands/usage/agent-canvas/git-sync — Correct the "Git Sync is not available for cloud backends" statement (and the troubleshooting row instructing users to confirm a local backend) to reflect org admin/owner access on cloud backends plus the member no-access state. Rationale: this page currently states the opposite of the new behavior.
• /openhands/usage/agent-canvas/customize-and-settings (Check MCP Server Health) — Document that remote MCP servers are testable on cloud backends via the app server and that stdio servers are not tested there. Rationale: this section already documents the health-check statuses.
• /openhands/usage/agent-canvas/managing-automations — Clarify who can create automations (view vs manage permission) to match the org-member add-menu fix. Rationale: this page documents editing/disable permissions but not creation.
• /openhands/usage/agent-canvas/release-notes/ — Add a new v1.22.0.mdx page following the existing format (see v1.20.0.mdx). Rationale: prior releases have dedicated release-notes pages.
• Needs maintainer triage for the sibling MCP save fix (PR #17467), the hidden-org filter (PR #17624), and the runtime version bumps (PR #17628) — verify whether any docs reference MCP cloud persistence, hidden/personal workspaces, or specific default runtime versions.

Source links

• https://github.com/OpenHands/OpenHands/releases/tag/v1.22.0
• https://github.com/OpenHands/OpenHands/pull/17276
• https://github.com/OpenHands/OpenHands/pull/17216
• https://github.com/OpenHands/OpenHands/pull/17581
• https://github.com/OpenHands/OpenHands/pull/17526
• https://github.com/OpenHands/OpenHands/pull/17617
• https://github.com/OpenHands/OpenHands/pull/17467
• https://github.com/OpenHands/OpenHands/pull/17466
• https://github.com/OpenHands/OpenHands/pull/17624
• https://github.com/OpenHands/OpenHands/pull/17606
• https://github.com/OpenHands/OpenHands/pull/17628

This issue was created by an AI agent (OpenHands) on behalf of the user.