mirror of
https://github.com/coder/coder.git
synced 2026-09-21 12:44:32 +08:00
Nick Vigilante
6acf32701e
Closes DOCS-426. Follow-up to [#26586](https://github.com/coder/coder/pull/26586) (DOCS-425, strip), which merged first. ## Problem The Vale problem matcher at `.github/vale-problem-matcher.json` hard-codes `"severity": "warning"`. Every Vale finding renders as a GitHub `warning` annotation, regardless of Vale's actual severity. Nick observed this on PR [#25501](https://github.com/coder/coder/pull/25501): error-level findings from `Coder.BrandNames` appear as warnings. This collapsed the doctrine's three-severity ladder (`error` / `warning` / `suggestion`) into a single advisory channel for the reader of a PR diff. This PR restores the ladder visually so contributors and reviewers see each rule's intended severity. ## Root cause GitHub Actions problem matchers expect either a regex capture group for severity or a hard-coded severity. Vale's `--output=line` format produces `path:line:col:rule:message` with severity stripped, so the matcher had no severity to capture and fell back on the hard-coded value. ## Fix ### Commit 1: severity rendering Switch the Vale prose lint step to `vale --output=JSON` and pipe through `jq` to emit GitHub workflow commands directly. Drop the problem matcher file. | Vale severity | GitHub workflow command | |---|---| | `suggestion` | `::notice::` | | `warning` | `::warning::` | | `error` | `::error::` | Message bodies are URL-encoded for `%`, `\r`, and `\n` per the GitHub Actions workflow command spec. The Vale step stays advisory (`continue-on-error: true`, `vale --no-exit`); rendering becomes correct but the step never fails the job. ### Commit 2: three-severity demo Three throwaway `Coder.Demo*` rules at `level: suggestion`, `level: warning`, and `level: error`, plus a `docs/.style/_vale-annotation-demo.md` file that triggers each rule exactly once. Together with the rendering fix above, this PR's CI surfaces three GitHub annotations in three distinct severities (notice, warning, error). Use the Files Changed view to inspect rendering. The demo files live permanently in `docs/.style/`, which is excluded from coder.com. They re-trigger annotations only on PRs that touch the demo file itself, so they don't pollute CI on day-to-day PRs. ## Sample output <img width="1443" height="1293" alt="image" src="https://github.com/user-attachments/assets/fb337315-7b55-40b3-9983-828b2d5399fc" /> <img width="1443" height="1293" alt="image" src="https://github.com/user-attachments/assets/b02d575d-5905-4c6d-b145-ad5df6e04f11" /> ## Out of scope Blocking merge on `error`-level findings is the natural next step but is sequenced as the **final** step of the prose-style rollout. It was prototyped in this PR (commit 3, since backed out) and verified end-to-end against the demo doc. The work moved to [DOCS-433](https://linear.app/codercom/issue/DOCS-433/block-merge-on-vale-error-level-findings-final-step-of-prose-style) so the corpus of enabled rules is broad enough by the time the gate lands that it catches real violations rather than novelty failures from a single rule. ## Expected CI state on this PR `lint-docs` passes. The three demo annotations render at lines 17 / 19 / 21 of `docs/.style/_vale-annotation-demo.md` as `::notice::`, `::warning::`, and `::error::` respectively. The `::error::` annotation does not fail the job because the Vale step is still advisory under this PR. Local verification of the rendering pipeline: ``` $ printf '%s\n' 'docs/.style/_vale-annotation-demo.md' \ | xargs -d '\n' vale --no-exit --output=JSON \ | jq -r '...' ::notice file=docs/.style/_vale-annotation-demo.md,line=17,col=3,title=Coder.DemoSuggestion::[Demo] Suggestion-level Vale annotation. ::warning file=docs/.style/_vale-annotation-demo.md,line=19,col=3,title=Coder.DemoWarning::[Demo] Warning-level Vale annotation. ::error file=docs/.style/_vale-annotation-demo.md,line=21,col=3,title=Coder.DemoError::[Demo] Error-level Vale annotation. ``` <details> <summary>Decision log</summary> - **Workflow commands vs custom Vale template + updated matcher**: chose workflow commands because the transform is a 10-line jq pipeline with no extra files to maintain, and it bypasses GitHub Actions problem-matcher limitations entirely. The custom-template option would have kept the matcher infrastructure but required an additional Go template file under `.github/`. - **Throwaway demo rules vs reusing existing rules**: chose throwaway because we wanted each severity to fire deterministically from a single unambiguous marker. Reusing existing rules would couple the demo to corpus content and obscure the signal. - **Demo persists vs drops before merge**: persists. The merge-gate constraint that originally forced the demo to drop is gone (deferred to DOCS-433). The four demo files live in `docs/.style/`, excluded from coder.com, and only annotate PRs that touch them. They double as a permanent canary so a future regression in severity rendering surfaces immediately on whichever PR introduces it, and as the verification artifact DOCS-433 uses when re-installing the merge gate. - **`docs/.style/_vale-annotation-demo.md` filename**: underscore prefix follows Coder convention for files that exist outside the normal docs taxonomy. Not surfaced on coder.com/docs because `docs/.style/` is excluded from the manifest, deploy workflow, and docs preview. - **Merge-block deferred to DOCS-433**: the rendering fix and the merge gate are independent changes. Shipping the rendering first lets contributors see the three-severity ladder while the rule catalogue is still small and the false-positive policy hasn't been stress-tested yet. The gate lands as the final step of the rollout, after the catalogue is broad enough that the gate covers real prose-style policy rather than one rule's enforcement. </details> --- *Filed via [Coder Agents](https://coder.com/docs/ai-coder/agents) on Nick's behalf.*
Coder is a self-hosted platform for cloud development environments and AI coding agents. Workspaces are defined with Terraform, connected through a secure Wireguard® tunnel, and automatically shut down when not used. Coder Agents runs a native AI coding agent whose loop executes in the control plane on your infrastructure, with no API keys in workspaces.
- Define cloud development environments in Terraform
- EC2 VMs, Kubernetes Pods, Docker Containers, etc.
- Automatically shutdown idle resources to save on costs
- Onboard developers in seconds instead of days
- Delegate coding work to AI agents on your infrastructure
- Bring any model (Anthropic, OpenAI, Google, Bedrock, self-hosted)
- No LLM credentials in workspaces, user identity on every action
- Centralized model governance, cost tracking, and audit logging
Quickstart
The most convenient way to try Coder is to install it on your local machine and experiment with provisioning cloud development environments using Docker (works on Linux, macOS, and Windows).
# First, install Coder
curl -L https://coder.com/install.sh | sh
# Start the Coder server (caches data in ~/.cache/coder)
coder server
# Navigate to http://localhost:3000 to create your initial user,
# create a Docker template and provision a workspace
Install
The easiest way to install Coder is to use the
install script for Linux
and macOS. For Windows, use the latest ..._installer.exe file from GitHub
Releases.
curl -L https://coder.com/install.sh | sh
You can run the install script with --dry-run to see the commands that will be used to install without executing them. Run the install script with --help for additional flags.
See install for additional methods.
Once installed, you can start a production deployment with a single command:
# Automatically sets up an external access URL on *.try.coder.app
coder server
# Requires a PostgreSQL instance (version 13 or higher) and external access URL
coder server --postgres-url <url> --access-url <url>
Use coder --help to get a list of flags and environment variables. See the install guides for a complete tutorial.
Documentation
Browse the documentation or visit a specific section below:
- Workspaces: Workspaces contain the IDEs, dependencies, and configuration information needed for software development
- Templates: Templates are written in Terraform and describe the infrastructure for workspaces
- Coder Agents: Delegate coding work to AI agents running on your self-hosted infrastructure
- Administration: Learn how to operate Coder
- Premium: Learn about paid features built for large teams
- IDEs: Connect your existing editor to a workspace
Support
Feel free to open an issue if you have questions, run into bugs, or have a feature request.
Join our Discord to provide feedback on in-progress features and chat with the community using Coder!
Integrations
New integrations are always in progress. Open an issue to request one. Contributions are welcome in any official or community repository.
Official
- Coder Registry: Templates, modules, and integrations for common development environments
- VS Code Extension: Open any Coder workspace in VS Code with a single click
- JetBrains Toolbox Plugin: Open any Coder workspace from JetBrains Toolbox with a single click
- JetBrains Gateway Plugin: Open any Coder workspace in JetBrains Gateway with a single click
- Dev Containers: Build development environments using
devcontainer.jsonon Docker, Kubernetes, and OpenShift - Kubernetes Log Stream: Stream Kubernetes Pod events to the Coder startup logs
- Self-Hosted VS Code Extension Marketplace: A private extension marketplace that works in restricted or airgapped networks integrating with code-server.
- GitHub Actions: An action to set up the Coder CLI in GitHub workflows
Community
- Community Templates: Community-contributed workspace templates in the Coder Registry
- Community Modules: Community-contributed modules to extend Coder templates
- Provision Coder with Terraform: Provision Coder on Google GKE, Azure AKS, AWS EKS, DigitalOcean DOKS, IBMCloud K8s, OVHCloud K8s, and Scaleway K8s Kapsule with Terraform
- Coder Template GitHub Action: A GitHub Action that updates Coder templates
- Discord: Chat with the community and provide feedback on in-progress features
Contributing
New contributors are always welcome. If you are new to the Coder codebase, see the contribution guide to get started.
Hiring
Apply on the careers page if you are interested in joining the team.