Repository navigation
feat: expose the workspace template to agent commands - #31606
Conversation
5c03d66 to
530e035
Compare
This comment has been minimized.
This comment has been minimized.
|
Chat: Review posted | View chat Review history
deep-review v0.13.0 | Round 1 | Last posted: Round 1, 3 findings (1 P3, 1 P4, 1 Nit), COMMENT. Review Finding inventoryFinding inventory: PR #31606Findings
Contested and acknowledgedLaw analysisNot run. Effective additions 95 (threshold 1000). Head 530e035. Round logRound 1Round type: round 1, full panel. Netero first pass: 1 P4 (CRF-1), no gate. Panel: ging-go, ryosuke, melody (specialists: Go files, Go API and package boundaries, proto/SDK serialization chain); pariston, mafuuu (core); bisky (tests changed), gon, leorio (once-per-PR floor); zoro (wildcard, random draw). Focused size 8 plus wildcard. Results: 1 P3, 1 P4, 1 Nit posted; Gon P2 on agent.go:1017 moved to out of scope (comment line unchanged and already inaccurate); Gon P2 on agent.go:1542 dropped (keep-argument: new entries sit under a comment that describes a different purpose; drop reason: the block already held CODER_WORKSPACE_ID and name variables, so the diff does not change the comment's accuracy). Bisky convert_test OOS item dropped as disproved. Name-mutability notes from Ryosuke, Pariston, Mafuuu merged into CRF-2. Reviewed against 67e216b..530e035. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
This comment has been minimized.
This comment has been minimized.
530e035 to
b0b4c1a
Compare
This comment was marked as outdated.
This comment was marked as outdated.
|
Squash message: |
BobbyHo
left a comment
There was a problem hiding this comment.
lgtm. Just left a minor (non-blocking) doc comment.
The agent now sets CODER_WORKSPACE_TEMPLATE_ID and CODER_WORKSPACE_TEMPLATE_NAME for every command it runs, from new template_id and template_name manifest fields. Scripts that depend on template-specific scripts, such as a personalize script calling coder exp sync wait, can now tell which template they run under. Like CODER_WORKSPACE_BUILD_ID, both are left unset when the server predates the fields.
release/2.39 shipped v2.15, so the template_id and template_name manifest fields belong to a new minor version. The agent dials v2.16.
The agent dials an Agent API version that only servers sending these manifest fields accept, so the nil checks for an older server never fire, and Coder does not support older servers. The template ID and name are always set: workspaces.template_id is NOT NULL and workspaces_expanded inner-joins templates. TestAgent_CoderEnvVars now checks exact values for every variable, which replaces the separate build ID and template tests and their Unset cases.
ManifestFromProto parses required IDs with uuid.FromBytes, as it does for agent_id, workspace_id, and the script and devcontainer IDs. The len > 0 guard on workspace_build_id existed for servers older than the field, which an agent at this API version cannot connect to, so a missing value now fails conversion instead of becoming uuid.Nil.
TestAgent_CoderEnvVars checked every predefined identity variable except CODER_WORKSPACE_ID. TestWorkspaceAgent_Metadata now checks the template fields against a manifest built from a real database, which the mocked TestGetManifest cannot show.
No page listed the CODER_WORKSPACE_* variables, so script authors had to read agent code to find them. The personalize section links to the list with one example.
The agent fetches the manifest once per connection to Coder, so a template, workspace, or user rename reaches new commands only after the agent reconnects. Scripts in a long-running workspace can otherwise expect the new name.
A running command keeps the environment it started with, and only new commands pick up a new name after the agent reconnects.
b0b4c1a to
88fa5fe
Compare
There was a problem hiding this comment.
Documentation Check
Blocking
-
docs/admin/templates/extending-templates/environment-variables.md(open) - The new "Variables the agent sets" section serves the end-user script author on a page that targets the template author.
Design notes
- The agent-set environment variable table, the rename caveat, and the rename-timing paragraph all describe what an in-workspace script reads, which is the end user's concern. They live on the template-author
environment-variables.mdpage.
Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.
|
|
||
| ## Variables the agent sets | ||
|
|
||
| The Coder agent sets these environment variables for every command it runs, including scripts and SSH sessions: |
There was a problem hiding this comment.
Blocking: The new "Variables the agent sets" table describes values an end user's in-workspace script reads, so it serves the end user (Dave) on a page that otherwise targets the template author (Perry), whose task here is writing coder_env resources. (Reader Advocate)
Evidence: the page's opening targets the template author ("Use the coder_env resource to inject environment variables into your workspace agents"); the table's value column is read by a script running inside the workspace.
To identify a template reliably, this belongs on the page the script author reads, docs/user-guides/workspace-dotfiles.md.
| The Coder agent sets these environment variables for every command it runs, including scripts and SSH sessions: | |
| Move the agent-set environment variable table to the workspace-dotfiles.md "Personalize script" section and cross-link from there. On this admin page, keep only the note that a `coder_env` resource or the agent's `env` block overrides these values, which is the one piece relevant to writing `coder_env`. |
There was a problem hiding this comment.
The template author reads these too. Every coder_script runs with them, including cron scripts that run long after Terraform rendered the template. A portable shell script can't use data.coder_workspace, and an interpolated value is fixed at build time. The table stays with the template's environment variables, and the dotfiles guide links to it for end users.
🤖 Posted using
/amend-reviewskill via Coder Agents.
| | `CODER_WORKSPACE_TEMPLATE_ID` | ID of the workspace's template | | ||
| | `CODER_WORKSPACE_TEMPLATE_NAME` | Name of the workspace's template | | ||
|
|
||
| Template names are unique only within an organization, and a template can be renamed. |
There was a problem hiding this comment.
Blocking: "Template names are unique only within an organization, and a template can be renamed" only changes what a reader does if that reader branches on the template name in a script, which is the end user (Dave) on docs/user-guides/workspace-dotfiles.md, not the template author this page targets. (Reader Advocate)
Evidence: the page's task is writing coder_env resources; the caution matters only to the script author who compares CODER_WORKSPACE_TEMPLATE_NAME.
| Template names are unique only within an organization, and a template can be renamed. | |
| Move this sentence to workspace-dotfiles.md next to the branch-on-template-name example (line 41), reframed for the script author. The related rename-timing paragraph you added ("commands that are already running keep the old name") is the same audience and should move with it. |
There was a problem hiding this comment.
Same reason: a template's script that reads CODER_WORKSPACE_TEMPLATE_NAME, for example a cron script or one shared across templates, depends on both the uniqueness and the rename timing, so the notes stay with the table.
🤖 Posted using
/amend-reviewskill via Coder Agents.
| | `CODER_WORKSPACE_ID` | ID of the workspace | | ||
| | `CODER_WORKSPACE_BUILD_ID` | ID of the workspace build that created the agent | | ||
| | `CODER_WORKSPACE_TEMPLATE_ID` | ID of the workspace's template | | ||
| | `CODER_WORKSPACE_TEMPLATE_NAME` | Name of the workspace's template | |
There was a problem hiding this comment.
The table says the value is the "Name of the workspace's template", so a reader does not learn that it is the template's internal name field, not its display name, and cannot know what string to compare against when adapting a script. (Newcomer)
Evidence: the value comes from templates.name (not display_name) via workspaces_expanded.
| | `CODER_WORKSPACE_TEMPLATE_NAME` | Name of the workspace's template | | |
| Use "The template's `name` field (not its display name)" for the value of `CODER_WORKSPACE_TEMPLATE_NAME`, so a script author knows to compare against `templates.name`. |
There was a problem hiding this comment.
Coder calls these the template's name and its display name: codersdk.Template has Name and DisplayName, the template settings form labels them "Name" and "Display name", and coder templates edit has --name and --display-name.
🤖 Posted using
/amend-reviewskill via Coder Agents.
Documentation CheckBlocking
Design notes
Findings for agents- id: audience-1
persona: audience
class: rule
blocking: true
file: docs/admin/templates/extending-templates/environment-variables.md
line: 134
quote: "The Coder agent sets these environment variables for every command it runs, including scripts and SSH sessions:"
evidence:
- docs/user-guides/workspace-dotfiles.md:36
rule: docs/.style/style-guide/audience-and-scope.md#pick-one-audience-per-page
problem: The new "Variables the agent sets" table lists values an end user's in-workspace script reads, so it serves the end user on a page that targets the template author writing coder_env resources.
fix: Move the agent-set environment variable table to the workspace-dotfiles.md "Personalize script" section and cross-link from there; on this admin page keep only the override caveat a template author acts on.
verified: true
- id: audience-2
persona: audience
class: rule
blocking: true
file: docs/admin/templates/extending-templates/environment-variables.md
line: 147
quote: "Template names are unique only within an organization, and a template can be renamed."
evidence:
- docs/user-guides/workspace-dotfiles.md:41
rule: docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs
problem: This product-behavior caveat only changes what a reader does if they branch on the template name in a script, which is the end user on workspace-dotfiles.md, not the template author this page targets.
fix: Cut the sentence and its rename-timing follow-up from this admin page and place them on workspace-dotfiles.md next to the branch-on-template-name example.
verified: true
- id: learner-1
persona: learner
class: suggestion
blocking: false
file: docs/admin/templates/extending-templates/environment-variables.md
line: 145
quote: "| `CODER_WORKSPACE_TEMPLATE_NAME` | Name of the workspace's template |"
evidence:
- agent/agent.go:1540-1552
rule: null
problem: The table says the value is the "Name of the workspace's template", so a reader does not learn that it is the template's internal name field, not its display name, and cannot know what string to compare against in a script.
fix: Use "The template's `name` field (not its display name)" for the value of `CODER_WORKSPACE_TEMPLATE_NAME`.
verified: trueAutomated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong. |
The agent now sets
CODER_WORKSPACE_TEMPLATE_IDandCODER_WORKSPACE_TEMPLATE_NAMEfor every command it runs, alongsideCODER_WORKSPACE_NAMEandCODER_WORKSPACE_BUILD_ID. Templates run different scripts in different orders, so a user's own script (for example a personalize script) needs to know which template it runs under to coordinate with that template's scripts.coderd sends the values in two new manifest fields,
template_idandtemplate_name, read from the workspace row.The Agent API goes to v2.16.
release/2.39shipped v2.15, so these fields start a new minor version. No new RPCs.CODER_WORKSPACE_BUILD_IDloses its nil checks from #30388, in the agent and inManifestFromProto. An agent only connects to a server that supports its API version, and every such server sends the build ID, so the checks never fired.The environment variables page now lists the variables the agent sets, and the personalize script docs link to it with an example.
Decision log
CODER_WORKSPACE_ID.workspaces.template_idis NOT NULL andworkspaces_expandedinner-joinstemplates, so both values are always present.ManifestFromProtoparses the build and template IDs withuuid.FromBytes, as it does for every required ID (agent_id,workspace_id, script and devcontainer IDs). Only IDs some agents lack, such asparent_id, areoptionalin the proto and parsed behind a nil check.TestAgent_CoderEnvVarsnow checks exact values for every variable it covers and absorbs the separate build ID test. ItsUnsetcase only covered the removed nil check.devcontainer.json(agent/agentcontainers/api.go). Those exist to build URLs such as the Zed${localEnv:...}link, and the template does not appear in one. Dev container sub-agents still get both variables for their commands, because they fetch their manifest from the same endpoint.CODER_WORKSPACE_TEMPLATE_VERSION. The version name is usually a generated name, which scripts cannot act on.CODER_AGENT_TOKENandGIT_SSH_COMMAND, are left out.