Thanks to visit codestin.com
Credit goes to github.com

Skip to content

fix(docs): document org-scoped admin configuration for agents (#28482) - #28584

Merged
mtojek merged 3 commits into
release/2.37from
backport/28482-to-2.37
Aug 25, 2026
Merged

fix(docs): document org-scoped admin configuration for agents (#28482)#28584
mtojek merged 3 commits into
release/2.37from
backport/28482-to-2.37

Conversation

@github-actions

Copy link
Copy Markdown
Contributor

Cherry-pick of #28482

Original PR: #28482 — docs: document org-scoped admin configuration for agents
Merge commit: 409049d
Requested by: @ethanndickson

Cherry-pick of 409049d onto release/2.37 had conflicts.
To resolve:
  git fetch origin backport/28482-to-2.37
  git checkout backport/28482-to-2.37
  git cherry-pick -x -m1 409049d
  # resolve conflicts
  git push origin backport/28482-to-2.37
Documents the organization scoping of Coder Agents admin configuration,
and corrects the navigation paths, access wording, and default-model
instructions that no longer matched the product. Documentation only, no
product code changes.

Follows #28473, which moved the organization model overrides into an
**Organization settings** section on **Admin settings > AI > Coder
Agents**. #28473 is merged, so this targets `main`.

Closes CODAGT-715

- **New page**
`docs/ai-coder/agents/platform-controls/organizations.md`, registered in
`docs/manifest.json`. Covers the deployment/organization scope split,
what an upgrade changes, how an organization without models or MCP
servers behaves, who configures each scope, and how model and MCP server
sharing works.
- **`models.md`**: models are organization-scoped while providers and
their credentials stay deployment-wide. Each organization has one
default model, and the first model added becomes it. Documents the
**Default** badge and the **Set as Coder Agents default model** form
option in place of the star action that no longer exists, and points
model overrides at **Organization settings**.
- **`getting-started.md`**: replaces the Owner-only claim with the
actual access model, adds an organization selection step, and uses the
**Add model** label.
- **`platform-controls/index.md`**: separates deployment-wide controls
from organization-scoped controls, documents personal model overrides
alongside the model configuration section rather than as an enforcement
caveat, and adds `--agents-allowed` plus the `agents-allowed:` search
filter.
- **`platform-controls/advisor.md`** and
**`platform-controls/virtual-desktop.md`**: the Advisor and Virtual
desktop settings are cards in the **Deployment settings** section of the
**Coder Agents** page, not sidebar entries. **Providers** is a sidebar
item, not a tab.
- **`platform-controls/mcp-servers.md`**: slug uniqueness is per
organization, the **Add server** label is correct, and the page is no
longer described as admin-only.
- **`architecture.md`**, **`index.md`**,
**`tasks-to-chats-migration.md`**: organization scope corrections and
organization-scoped model routes.
- Breadcrumbs standardized to **Admin settings > AI > ...**, verified
against `AdminSettings.tsx` and `AISettingsSidebarView.tsx`.

<details>
<summary>Review follow-ups</summary>

The first revision leaked implementation detail into user-facing pages
and contained several claims that did not match the UI. The follow-up
commit removed and corrected the following.

Removed as implementation detail:

- The `chat_model_config` RBAC resource, its actions, and the token
scopes.
- The `available`, `unavailable_reason`, and `unsupported_providers`
response fields, along with the `missing_api_key`, `fetch_failed`, and
`user_api_key_required` values.
- Role and permission tables, ACL storage mechanics, audit internals,
and JSON error bodies on the new organizations page.
- Migration mechanics with no effect on what a user does.

Corrected against the product:

- The star action does not exist. The list shows a **Default** badge and
the add/edit form offers **Set as Coder Agents default model**
(`ModelRow.tsx`, `ModelFormFields.tsx`).
- The first model added to an organization becomes its default
automatically (`coderd/exp_chats.go`). An organization without a stored
default does not fail every chat, so that claim is gone.
- Advisor and Virtual desktop are cards under **Deployment settings**
(`CoderAgentsPageView.tsx`).
- The MCP servers page does not require deployment configuration edit
permission (`AISettingsSidebarView.tsx`).
- Button labels: **Add model** and **Add server**.
- The organization query parameter is `org`, confirmed by
`modelOrganizationSearchParam`.

Left alone deliberately: pre-existing defects outside the introduced
text, including the `/api/v2/chats` route prefixes, create-chat examples
missing `organization_id`, and the pre-existing MCP permissions table.

</details>

- `pnpm run format-docs` and `pnpm run lint-docs` pass.
- `make lint/emdash` passes. No emdash or endash added.
- `grep -rn "Defaults & overrides" docs/` returns nothing.
- Every navigation path, button label, and access claim checked against
the corresponding file under `site/src/pages/AISettingsPage/` and
`site/src/modules/management/`.

---

This pull request was generated by Coder Agents on behalf of
@ethanndickson.

(cherry picked from commit 409049d)
@ethanndickson ethanndickson changed the title [CONFLICT] docs: document org-scoped admin configuration for agents (#28482) docs: document org-scoped admin configuration for agents (#28482) Aug 25, 2026
@github-actions

github-actions Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor Author

@github-actions

Copy link
Copy Markdown
Contributor Author

👋 Hey @github-actions[bot]!

This PR is targeting the release/2.37 release branch, but its title does not start with fix: or fix(scope):.

Only bug fixes should be cherry-picked to release branches. If this is a bug fix, please update the PR title to match the conventional commit format:

fix: description of the bug fix
fix(scope): description of the bug fix

If this is not a bug fix, it likely should not target a release branch.

@ethanndickson
ethanndickson requested a review from mtojek August 25, 2026 16:33
@mtojek
mtojek self-requested a review August 25, 2026 16:35

@mtojek mtojek left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like there are some conflicts now.

@ethanndickson ethanndickson changed the title docs: document org-scoped admin configuration for agents (#28482) fix(docs): document org-scoped admin configuration for agents (#28482) Aug 25, 2026
@ethanndickson
ethanndickson requested a review from mtojek August 25, 2026 16:54

Copy link
Copy Markdown
Member

Resolved the cherry-pick conflict, merged the latest release/2.37, and preserved the newer title-generation endpoint documentation while applying the organization-scoped model route changes. All checks are green. Re-requesting review.

@mtojek
mtojek merged commit d7fef22 into release/2.37 Aug 25, 2026
32 checks passed
@mtojek
mtojek deleted the backport/28482-to-2.37 branch August 25, 2026 18:20
@github-actions github-actions Bot locked and limited conversation to collaborators Aug 25, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

cherry-pick/v2.37 Cherry-pick PR targeting release/2.37

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants