From cff0cd1e4ce64da9ac1aced73e35d0e8fd8c3f66 Mon Sep 17 00:00:00 2001 From: freeqaz Date: Sat, 24 Oct 2026 19:54:32 +0000 Subject: [PATCH] docs: name unknown filesystem keys in the startup notice and archive older notices The 2026-10-24 OpenShell Sandbox policy notice said that, apart from a slash-only readOnly path, none of the newly refused settings could deploy an Agent. An unknown policy.filesystem key (a readwrite typo, for example) was ignored and deployed; startup now refuses it. The notice's exception names it. breaking-changes.md was at 2492 of its 2500 words, so the 2026-10-22 and 2026-10-16 notices move to a new before-2026-10-23 page, with the intro link lists on every notice page and a docs.json nav entry. Finding 2345. --- docs/docs.json | 4 ++ .../guides/deploy/breaking-changes-archive.md | 3 +- .../breaking-changes-before-2026-10-10.md | 1 + .../breaking-changes-before-2026-10-11.md | 1 + .../breaking-changes-before-2026-10-12.md | 1 + .../breaking-changes-before-2026-10-13.md | 1 + .../breaking-changes-before-2026-10-15.md | 4 +- .../breaking-changes-before-2026-10-23.md | 66 +++++++++++++++++++ docs/guides/deploy/breaking-changes.md | 64 ++---------------- 9 files changed, 83 insertions(+), 62 deletions(-) create mode 100644 docs/guides/deploy/breaking-changes-before-2026-10-23.md diff --git a/docs/docs.json b/docs/docs.json index 6e8aeea928..268b914bcb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -500,6 +500,10 @@ "page": "guides/deploy/breaking-changes", "label": "Breaking Changes" }, + { + "page": "guides/deploy/breaking-changes-before-2026-10-23", + "label": "Breaking Changes Before 2026-10-23" + }, { "page": "guides/deploy/breaking-changes-before-2026-10-15", "label": "Breaking Changes Before 2026-10-15" diff --git a/docs/guides/deploy/breaking-changes-archive.md b/docs/guides/deploy/breaking-changes-archive.md index 7f442cdb49..5d7da8441c 100644 --- a/docs/guides/deploy/breaking-changes-archive.md +++ b/docs/guides/deploy/breaking-changes-archive.md @@ -1,7 +1,8 @@ # Earlier breaking-change notices These [breaking-change notices](breaking-changes.md) are older than the ones -on that page and in the +on that page, in the +[notices before 2026-10-23](breaking-changes-before-2026-10-23.md) and in the [notices before 2026-10-15](breaking-changes-before-2026-10-15.md), and newer than the [notices before 2026-10-13](breaking-changes-before-2026-10-13.md). They still apply when you upgrade from a source commit older than their date. Entries are diff --git a/docs/guides/deploy/breaking-changes-before-2026-10-10.md b/docs/guides/deploy/breaking-changes-before-2026-10-10.md index 64fff0cacf..a8e10c9ef1 100644 --- a/docs/guides/deploy/breaking-changes-before-2026-10-10.md +++ b/docs/guides/deploy/breaking-changes-before-2026-10-10.md @@ -2,6 +2,7 @@ These [breaking-change notices](breaking-changes.md) are dated before 2026-10-10; newer ones are on that page, in the +[notices before 2026-10-23](breaking-changes-before-2026-10-23.md), in the [notices before 2026-10-15](breaking-changes-before-2026-10-15.md), in the [earlier notices](breaking-changes-archive.md), in the [notices before 2026-10-13](breaking-changes-before-2026-10-13.md), in the diff --git a/docs/guides/deploy/breaking-changes-before-2026-10-11.md b/docs/guides/deploy/breaking-changes-before-2026-10-11.md index ef5a3cba4a..1aed6b2b99 100644 --- a/docs/guides/deploy/breaking-changes-before-2026-10-11.md +++ b/docs/guides/deploy/breaking-changes-before-2026-10-11.md @@ -2,6 +2,7 @@ These [breaking-change notices](breaking-changes.md) are dated 2026-10-10; newer ones are on that page, in the +[notices before 2026-10-23](breaking-changes-before-2026-10-23.md), in the [notices before 2026-10-15](breaking-changes-before-2026-10-15.md), in the [earlier notices](breaking-changes-archive.md), in the [notices before 2026-10-13](breaking-changes-before-2026-10-13.md) and in the diff --git a/docs/guides/deploy/breaking-changes-before-2026-10-12.md b/docs/guides/deploy/breaking-changes-before-2026-10-12.md index 87ca82e603..6dc666dde4 100644 --- a/docs/guides/deploy/breaking-changes-before-2026-10-12.md +++ b/docs/guides/deploy/breaking-changes-before-2026-10-12.md @@ -2,6 +2,7 @@ These [breaking-change notices](breaking-changes.md) are dated 2026-10-11; newer ones are on that page, in the +[notices before 2026-10-23](breaking-changes-before-2026-10-23.md), in the [notices before 2026-10-15](breaking-changes-before-2026-10-15.md), in the [earlier notices](breaking-changes-archive.md) and in the [notices before 2026-10-13](breaking-changes-before-2026-10-13.md), and older ones are in the diff --git a/docs/guides/deploy/breaking-changes-before-2026-10-13.md b/docs/guides/deploy/breaking-changes-before-2026-10-13.md index f2ac81d1bc..ed5a73a5d7 100644 --- a/docs/guides/deploy/breaking-changes-before-2026-10-13.md +++ b/docs/guides/deploy/breaking-changes-before-2026-10-13.md @@ -2,6 +2,7 @@ These [breaking-change notices](breaking-changes.md) are dated 2026-10-12; newer ones are on that page, in the +[notices before 2026-10-23](breaking-changes-before-2026-10-23.md), in the [notices before 2026-10-15](breaking-changes-before-2026-10-15.md) and in the [earlier notices](breaking-changes-archive.md), and older ones are in the [notices before 2026-10-12](breaking-changes-before-2026-10-12.md). They still diff --git a/docs/guides/deploy/breaking-changes-before-2026-10-15.md b/docs/guides/deploy/breaking-changes-before-2026-10-15.md index 6f17ce46e0..b440779de5 100644 --- a/docs/guides/deploy/breaking-changes-before-2026-10-15.md +++ b/docs/guides/deploy/breaking-changes-before-2026-10-15.md @@ -1,7 +1,9 @@ # Breaking-change notices before 2026-10-15 These [breaking-change notices](breaking-changes.md) are dated 2026-10-14; -newer ones are on that page, and older ones are in the +newer ones are on that page and in the +[notices before 2026-10-23](breaking-changes-before-2026-10-23.md), and older +ones are in the [earlier notices](breaking-changes-archive.md). They still apply when you upgrade from a source commit older than their date. Entries are newest first. Steps marked _untested_ have not been run against a real Installation. diff --git a/docs/guides/deploy/breaking-changes-before-2026-10-23.md b/docs/guides/deploy/breaking-changes-before-2026-10-23.md new file mode 100644 index 0000000000..bdcbf13648 --- /dev/null +++ b/docs/guides/deploy/breaking-changes-before-2026-10-23.md @@ -0,0 +1,66 @@ +# Breaking-change notices before 2026-10-23 + +These [breaking-change notices](breaking-changes.md) are dated 2026-10-16 to +2026-10-22; newer ones are on that page, and older ones are in the +[notices before 2026-10-15](breaking-changes-before-2026-10-15.md). They still +apply when you upgrade from a source commit older than their date. Entries are +newest first. Steps marked _untested_ have not been run against a real +Installation. + +## 2026-10-22: Credential Proxy retires the repository broker selections + +**What breaks.** The Credential Proxy release (#2487) refuses these at Helm +render, or at API and worker startup and in the upgrade check: + +- Helm `repositoryCredentials` with the GitHub App signing broker: + `authority` must be `prepared-git` with `preparedCustodySecretName`; another + value fails with `GitHub App signing gateway retired: ...`. The broker's + service config refuses `backend.kind` `github-app` and `github-app-registry`. +- Installation `drivers.repo`: configure `repository.nativeSender` with + `repository.preparedGitHub`, or protected Git through `repository.openShell`. + A Backend's own `drivers.repo` member stays. +- Installation or Backend `drivers.conduit`: select + `drivers.credential_proxy` instead. +- Helm `openshellGit.mode: broker-trial`: only `protected` remains. + +The migrator also refuses a database from an earlier Credential Proxy preview. + +**Who is affected.** Installations that used the native repository broker +(Installation `drivers.repo`, Helm `repositoryCredentials.enabled`). +`drivers.conduit`, `broker-trial` and the preview database refusal affect only +Credential Proxy preview builds. + +**How to tell.** Helm render fails for `broker-trial` and the broker settings +above. The upgrade check prints the startup refusals, for example +`drivers.repo native admission is retired. ...`, but the `startup-error` and +`worker.startup-error` logs show only `STARTUP_FAILED` or +`WORKER_STARTUP_FAILED`. The migrator (`db:migrate --check`) names a preview +history as unsupported. + +**Steps.** Before upgrading, drain accepted repository work on the original +release, which alone can settle it, then follow the +[Credential Proxy upgrade](credential-proxy-upgrade.md). Do not replay uncertain +work. + +## 2026-10-16: stored model provider settings are checked at deploy + +**What breaks.** On every Compute, deploying or redeploying an Agent runs the +Configuration save's model provider rules on the stored Configuration. A +Configuration an older build stored with a provider or model `baseUrl` that is +not an absolute `http` or `https` URL (`ftp://models.example/v1`, `/v1`, +`https:/v1`), an `api` the runtime does not support, or a header name that is +not a valid HTTP field name used to deploy, and then failed at the model probe +or not at all. Deployment now answers `400` and creates no version, even for a +provider the Agent does not use. A provisioning attempt queued before the +upgrade is rejected without retry. + +**Who is affected.** Agents whose stored Configuration holds such a value. +Header names were already checked at deploy on Kubernetes Compute. + +**How to tell.** The deploy `400` carries the save's message, such as +`Configuration field /models/providers//baseUrl must be an absolute http or https URL.` +or `... must name a model API the runtime supports, ...`. A rejected queued +attempt records `PROVISIONING_REJECTED` with the same message. + +**Steps.** Edit the Configuration: fix or remove the field the message names, +save, and deploy again. diff --git a/docs/guides/deploy/breaking-changes.md b/docs/guides/deploy/breaking-changes.md index dfe2145a74..78f83c6b1d 100644 --- a/docs/guides/deploy/breaking-changes.md +++ b/docs/guides/deploy/breaking-changes.md @@ -5,6 +5,7 @@ main can refuse or break an Installation that an older build created. Each change like that gets an entry here: what breaks, who is affected, how to tell, and the steps. Before an upgrade, read every entry dated after the source commit you run now, here, in the +[notices before 2026-10-23](breaking-changes-before-2026-10-23.md), in the [notices before 2026-10-15](breaking-changes-before-2026-10-15.md), in the [earlier notices](breaking-changes-archive.md), in the [notices before 2026-10-13](breaking-changes-before-2026-10-13.md), in the @@ -70,8 +71,9 @@ failed each dedicated deploy after its predecessors had stopped. **Who is affected.** Only Installations whose OpenShell Sandbox settings use one of these values. Apart from a slash-only path such as `//` in -`policy.filesystem.readOnly` (earlier builds refused only `/` there), none of -them could deploy an Agent. +`policy.filesystem.readOnly` (earlier builds refused only `/` there) and an +unknown `policy.filesystem` key such as a `readwrite` typo (earlier builds +ignored it), none of them could deploy an Agent. **How to tell.** Startup fails with `STARTUP_FAILED`, and the Installation loader names the setting, for example `/policy/process/runAsUser`. @@ -308,61 +310,3 @@ broker to protected OpenShell Git or an installed sender, and kept the peer. **Steps.** Delete `network.repositoryCredentials` from the Compute configuration, keep its other `network` settings, and upgrade again. - -## 2026-10-22: Credential Proxy retires the repository broker selections - -**What breaks.** The Credential Proxy release (#2487) refuses these at Helm -render, or at API and worker startup and in the upgrade check: - -- Helm `repositoryCredentials` with the GitHub App signing broker: - `authority` must be `prepared-git` with `preparedCustodySecretName`; another - value fails with `GitHub App signing gateway retired: ...`. The broker's - service config refuses `backend.kind` `github-app` and `github-app-registry`. -- Installation `drivers.repo`: configure `repository.nativeSender` with - `repository.preparedGitHub`, or protected Git through `repository.openShell`. - A Backend's own `drivers.repo` member stays. -- Installation or Backend `drivers.conduit`: select - `drivers.credential_proxy` instead. -- Helm `openshellGit.mode: broker-trial`: only `protected` remains. - -The migrator also refuses a database from an earlier Credential Proxy preview. - -**Who is affected.** Installations that used the native repository broker -(Installation `drivers.repo`, Helm `repositoryCredentials.enabled`). -`drivers.conduit`, `broker-trial` and the preview database refusal affect only -Credential Proxy preview builds. - -**How to tell.** Helm render fails for `broker-trial` and the broker settings -above. The upgrade check prints the startup refusals, for example -`drivers.repo native admission is retired. ...`, but the `startup-error` and -`worker.startup-error` logs show only `STARTUP_FAILED` or -`WORKER_STARTUP_FAILED`. The migrator (`db:migrate --check`) names a preview -history as unsupported. - -**Steps.** Before upgrading, drain accepted repository work on the original -release, which alone can settle it, then follow the -[Credential Proxy upgrade](credential-proxy-upgrade.md). Do not replay uncertain -work. - -## 2026-10-16: stored model provider settings are checked at deploy - -**What breaks.** On every Compute, deploying or redeploying an Agent runs the -Configuration save's model provider rules on the stored Configuration. A -Configuration an older build stored with a provider or model `baseUrl` that is -not an absolute `http` or `https` URL (`ftp://models.example/v1`, `/v1`, -`https:/v1`), an `api` the runtime does not support, or a header name that is -not a valid HTTP field name used to deploy, and then failed at the model probe -or not at all. Deployment now answers `400` and creates no version, even for a -provider the Agent does not use. A provisioning attempt queued before the -upgrade is rejected without retry. - -**Who is affected.** Agents whose stored Configuration holds such a value. -Header names were already checked at deploy on Kubernetes Compute. - -**How to tell.** The deploy `400` carries the save's message, such as -`Configuration field /models/providers//baseUrl must be an absolute http or https URL.` -or `... must name a model API the runtime supports, ...`. A rejected queued -attempt records `PROVISIONING_REJECTED` with the same message. - -**Steps.** Edit the Configuration: fix or remove the field the message names, -save, and deploy again.