Skip to content

docs: document org-scoped admin configuration for agents - #28482

Merged
ethanndickson merged 5 commits into
mainfrom
ethan/codagt-715-document-org-scoped-admin-configuration-for-agents
Aug 25, 2026
Merged

ethanndickson merged 5 commits into
mainfrom
ethan/codagt-715-document-org-scoped-admin-configuration-for-agents

Conversation

@ethanndickson

@ethanndickson ethanndickson commented Aug 24, 2026 •

Copy link
Copy Markdown
Member

Summary

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

Changes

  • 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.
Review follow-ups

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.

Testing

  • 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.

@linear-code

ghost commented Aug 24, 2026

Copy link
Copy Markdown

CODAGT-715

@github-actions

ghost commented Aug 24, 2026 •

Copy link
Copy Markdown
Contributor

@ethanndickson ethanndickson changed the title ethan/codagt 715 document org scoped admin configuration for agents docs(docs/ai-coder/agents): document org-scoped admin configuration Aug 24, 2026
@ethanndickson
ethanndickson force-pushed the ethan/codagt-715-document-org-scoped-admin-configuration-for-agents branch from 53bcaa9 to 1de9483 Compare August 24, 2026 15:57
Base automatically changed from overrides-scoping-0sy9 to main August 24, 2026 16:43
@ethanndickson
ethanndickson force-pushed the ethan/codagt-715-document-org-scoped-admin-configuration-for-agents branch 2 times, most recently from 4b50da3 to 0084b6f Compare August 24, 2026 17:51
Comment thread docs/ai-coder/agents/models.md Resolved
Comment thread docs/ai-coder/agents/models.md Resolved
Comment thread docs/ai-coder/agents/models.md Resolved
Comment thread docs/ai-coder/agents/models.md Resolved
Comment thread docs/ai-coder/agents/models.md Resolved
Comment thread docs/ai-coder/agents/models.md Resolved
Comment thread docs/ai-coder/agents/models.md Resolved
Comment thread docs/ai-coder/agents/models.md Resolved
@ethanndickson
ethanndickson marked this pull request as ready for review August 25, 2026 12:37

ghost left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2292147da3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +189 to +191
Users with access to an organization's MCP servers can open the **MCP servers**
settings page. Coder enables the edit controls for the users who can manage the
selected organization's servers.

ghost Aug 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Restore the deployment-admin caveat for user OIDC

For an organization admin managing an organization-scoped server, this replacement suggests that the available edit controls cover every authentication method, but authorizeUserOIDCMCPServerConfig in coderd/mcp.go rejects creating a server with auth_type=user_oidc without deployment_config:update, and the update path rejects any change touching such a server with HTTP 403. The UI likewise hides that option and disables editing existing user-OIDC servers for organization-only admins. Because this page still documents User OIDC as an authentication method, retain the removed deployment-permission exception.

Useful? React with 👍 / 👎.

ghost left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM with changes :shipit: 🚀

commit message formats, preferred libraries, or repository-specific context.

This setting is available under **AI Settings** > **Coder Agents** > **Instructions** and is only accessible to administrators. Developers do not see or interact with it.
This setting is available under **Admin settings** > **AI** > **Coder Agents** > **Instructions** and is only accessible to administrators. Developers do not see or interact with it.

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
This setting is available under **Admin settings** > **AI** > **Coder Agents** > **Instructions** and is only accessible to administrators. Developers do not see or interact with it.
This setting is available under **Admin settings** > **AI** > **Coder Agents** > **Instructions** and is only accessible to administrators. Developers can't access or interact with it.

Use `coder templates create --agents-allowed=false` or `coder templates edit --agents-allowed=false <template>` for a single template.
Use the search filter `agents-allowed:false` on `GET /api/v2/templates` to list the templates that block agents.

See [Template Optimization](./template-optimization.md) for best practices on writing

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
See [Template Optimization](./template-optimization.md) for best practices on writing
Check out [Template Optimization](./template-optimization.md) for best practices on writing

1. Navigate to **AI Settings** > **Coder Agents** > **MCP servers**.
1. Click **Add**.
1. Navigate to **Admin settings** > **AI** > **Coder Agents** > **MCP servers**.
1. Click **Add server**.

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
1. Click **Add server**.
1. Select **Add server**.

1. Navigate to **Admin settings** > **AI** > **Coder Agents** > **MCP servers**.
1. Click **Add server**.
1. Fill in the configuration fields described below.
1. Click **Save**.

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
1. Click **Save**.
1. Select **Save**.

Comment on lines +45 to +51
1. Every existing chat model moves to the default organization.
1. Every existing MCP server moves to the default organization, with its credentials intact.
1. Every moved model and MCP server stays available to the default organization's **Everyone** group, so current members keep access.
1. The previous default model becomes the default model of the default organization.
1. Coder removes the existing admin and personal model overrides.
1. Coder ignores the previous Advisor model override, so you must set it again.
1. The deployment-wide template allowlist becomes the per-template **Allow Coder Agents to create workspaces using this template** setting.

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
1. Every existing chat model moves to the default organization.
1. Every existing MCP server moves to the default organization, with its credentials intact.
1. Every moved model and MCP server stays available to the default organization's **Everyone** group, so current members keep access.
1. The previous default model becomes the default model of the default organization.
1. Coder removes the existing admin and personal model overrides.
1. Coder ignores the previous Advisor model override, so you must set it again.
1. The deployment-wide template allowlist becomes the per-template **Allow Coder Agents to create workspaces using this template** setting.
- Every existing chat model moves to the default organization.
- Every existing MCP server moves to the default organization, with its credentials intact.
- Every moved model and MCP server stays available to the default organization's **Everyone** group, so current members keep access.
- The previous default model becomes the default model of the default organization.
- Coder removes the existing admin and personal model overrides.
- Coder ignores the previous Advisor model override, so you must set it again.
- The deployment-wide template allowlist becomes the per-template **Allow Coder Agents to create workspaces using this template** setting.

Nit: suggesting an unordered list here.

Comment thread docs/ai-coder/agents/models.md Outdated

1. Navigate to **Admin settings** > **AI** > **Models**.
1. Click **Add** and select the provider for the new model.
1. Click **Add model** and select the provider for the new model.

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
1. Click **Add model** and select the provider for the new model.
1. Select **Add model** and select the provider for the new model.

1. Select the organization that owns the model.
1. Open the model, or click **Add model** to create a new one.
1. Select **Set as Coder Agents default model**.
1. Click **Save**.

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
1. Click **Save**.
1. Select **Save**.

Comment on lines +77 to +78
1. Navigate to **Admin settings** > **AI** > **Models**, select the correct
organization, add at least one model, and set it as the default.

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
1. Navigate to **Admin settings** > **AI** > **Models**, select the correct
organization, add at least one model, and set it as the default.
1. Navigate to **Admin settings** > **AI** > **Models**.
1. Select the correct organization.
1. Add at least one model, and set it as the default.

Comment on lines +512 to +513
List the available models in an organization to verify at least one provider is
configured and reachable:

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
List the available models in an organization to verify at least one provider is
configured and reachable:
List the available models in an organization to verify at least one provider is configured and reachable:

Comment on lines +644 to +645
- [ ] At least one LLM model is configured in the organization and returned by
`/organizations/{organization}/chats/models`

ghost Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
- [ ] At least one LLM model is configured in the organization and returned by
`/organizations/{organization}/chats/models`
- [ ] At least one LLM model is configured in the organization and returned by `/organizations/{organization}/chats/models`

@ethanndickson ethanndickson changed the title docs(docs/ai-coder/agents): document org-scoped admin configuration docs: document org-scoped admin configuration for agents Aug 25, 2026
Ethan Dickson added 4 commits August 25, 2026 15:49
Coder Agents settings now belong to an organization. Document the new
scope split, the permissions that control edit access, and the new
Organization settings section that holds model overrides.

Add a new "Organization scope" page. Update the models, getting started,
platform controls, MCP servers, advisor, architecture, and migration
pages for the new scope. Correct stale breadcrumbs and API routes.
…odel wording

Remove implementation details from the organization scope documentation.
Correct the Advisor and Virtual desktop locations to the Deployment
settings section. Correct the Add model and Add server button labels.
Replace the star action with the Default badge and the model form option.
Document that the first model of an organization becomes its default.
@ethanndickson
ethanndickson force-pushed the ethan/codagt-715-document-org-scoped-admin-configuration-for-agents branch from 08ca373 to 3a695d6 Compare August 25, 2026 15:50
@ethanndickson
ethanndickson merged commit 409049d into main Aug 25, 2026
@ethanndickson
ethanndickson deleted the ethan/codagt-715-document-org-scoped-admin-configuration-for-agents branch August 25, 2026 16:24
@github-actions

ghost commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Cherry-pick PR created: #28584 (⚠️ conflicts need manual resolution)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants