Adds `Coder.AbbreviationFirstUse`, a Vale rule that requires each abbreviation to be expanded on its first use on a page, in the form "Expanded Form (ABBR)". It supports [WCAG 2.2 Level AAA Success Criterion 3.1.4 (Abbreviations)](https://www.w3.org/TR/WCAG22/#abbreviations). Following the "Adding a Vale rule" pattern in `docs/.style/README.md`, the PR has two commits: the cleanup first, then the enable. ## Cleanup commit 431 first uses expanded across 167 pages, so the rule ships with zero findings across `docs/`, excluding `docs/.style/style-guide/`. The branch was rebuilt on current `main`, so pages added or moved since the first draft are covered. - Where the first use is a bold UI label (**CA Path**, **Add redirect URI**, **Redirect URI**), the label stays as the UI shows it and the expansion goes elsewhere in the same paragraph or list item. - Reversed forms such as "PKCE (Proof Key for Code Exchange)" are flipped to the expanded-first form. - A few sentences took a small rewording to fit the expansion: list steps that would pass the 20-word limit (`Coder.StepLength`), and spots where the expansion would nest parentheses. - MITM is expanded as "machine-in-the-middle" rather than "man-in-the-middle". Every use describes the AI Gateway Proxy intercepting traffic on purpose, so "on-path attacker" doesn't fit. The inclusive-language table on `accessibility-and-inclusion.md` gains the substitution: "on-path attacker" for the attack, "machine-in-the-middle" for the feature. - Unrelated fixes on lines already being edited: `DERP MAP` → `DERP map`, and `ENV` → "environment variable" in `faqs.md`. ## Enable commit **Rule design.** The rule is a `conditional`. `first` matches 2 to 6 capitals, each optionally followed by digits (`EC2`, `P2P`), and a lookahead lets a plural `s` count as a use of the singular. `second` captures the abbreviation in `word (ABBR)`, including `(CI/CD)` and `(PCI DSS)` pairs. Vale collects the captures across the page's blocks in document order, so a later expansion doesn't cover an earlier use. Within a single paragraph, list item, or table cell, an expansion anywhere in the block counts. **Scope.** `scope: ~heading` skips headings, because a page title often names an abbreviation that the first paragraph then expands. Vale already skips front matter, code blocks, inline code, and link URLs. `.vale.ini` turns the rule off for the pages generated from Go source that `Coder.UnitSpacing` already skips: `docs/reference/{api,cli}/*.md`, `configuration-reference.md`, and `prometheus.md`. **Severity: `warning`.** Whether an abbreviation is familiar enough to skip is a judgment call, so this is guidance with legitimate exceptions, not hard policy. **Exceptions**, each group commented in the rule file: | Group | Entries | Reason | | --- | --- | --- | | Known to every reader | AI, API, AWS, CLI, CPU, DNS, GCP, HTTP(S), ID, IDE, IP, JSON, OS, PR, RAM, SDK, SQL, SSH, TLS, UI, URL, VM, YAML | Abbreviations every reader of the docs knows. Plurals such as VMs and SDKs pass too | | Units, clock times, file and package formats | GB, KB, MB, AM, PM, CSV, GIF, JPEG, PDF, PNG, RPM, SVG, VSIX, ZIP | Readers know these by the abbreviation, not the expansion | | Not abbreviations | NOTE, TIP, OK, README, SKILL, ALL, AND, ANY, ERROR, MUST, NOT, ON, OR, DELETE, GET, POST, PUT, ILIKE, VACUUM, LOGIN, PLAIN, NUL, CRON, TERM, DOCS, `DOC\d+`, `RFC\d+`, TL, DR | Alert labels, file names, emphasis in capitals, HTTP methods, SQL keywords, SMTP auth mechanisms, rule labels in `docs/AGENTS.md`, RFC numbers, TL;DR | | Names written in capitals | VS, IDEA, IU, NGINX, SUSE, GNU, XFCE, DX, IBM, DCV, TRAMP, MSYS2, NET, VSX, ARM, AMD, GPT, AES, GCM, HMAC, HS256, RSA, SHA, SHA256 | The capitals are the product, company, or algorithm name (VS Code, IntelliJ IDEA, .NET, Open VSX, Amazon DCV, AMD) | The "known to every reader" group is the list that needs judgment, and it's the one to push back on. The other groups only stop the regex from treating words and names as abbreviations. **Documentation.** A new "Expand abbreviations on first use" section on `accessibility-and-inclusion.md`, and the style guide README's checks table, coverage table, and rule counts (90 → 91 rules, 22 → 23 tool-checked). ## Known limits - The rule checks that an expansion exists, not that it's correct: any word followed by `(ABBR)` satisfies it. - An abbreviation in an image's alt text is checked before the paragraph around it, so one alt text (`aws-marketplace.md`) carries its own expansion. - Some expansions read heavily in dense table cells and inline lists, for example the four Kubernetes services in `docker-in-workspaces.md`. They're correct, but a reviewer may prefer adding a specific abbreviation to the exceptions instead. ## Testing - `vale docs/` (Vale 3.7.1 through mise): zero `Coder.AbbreviationFirstUse` findings. Findings from every other rule match `main` file for file. - `pnpm run format-docs`, `pnpm run lint-docs`, `scripts/check_emdash.sh`, and `make lint/prose` run clean, and the repository pre-commit hooks (including `lint/style-claims`) pass on both commits. Linear: DOCS-1311 Generated by Coder Agents on behalf of @nickvigilante.
4.2 KiB
4.2 KiB
title
| title |
|---|
| Test and publish Coder templates through CI/CD |
Overview
This guide demonstrates how to test and publish Coder templates in a Continuous Integration (CI) pipeline using the coder/setup-action. This workflow ensures your templates are validated, tested, and promoted seamlessly.
Prerequisites
- Install and configure Coder CLI in your environment.
- Install Terraform CLI in your CI environment.
- Create a headless user with the user roles and permissions to manage templates and run workspaces.
Create the headless user
Warning
Creating users with
--login-type noneis deprecated. For Premium deployments, use service accounts instead. For open source software (OSS) deployments, use a regular account with password, GitHub, or OpenID Connect (OIDC) authentication.
For Premium deployments, create a service account:
coder users create \
--username machine-user \
--service-account
coder tokens create --user machine-user --lifetime 8760h
# Copy the token and store it in a secret in your CI environment with the name `CODER_SESSION_TOKEN`
For OSS deployments, create a regular user:
coder users create \
--username machine-user \
--email machine-user@example.com \
--login-type password
coder tokens create --user machine-user --lifetime 8760h
# Copy the token and store it in a secret in your CI environment with the name `CODER_SESSION_TOKEN`
Example GitHub Action Workflow
This example workflow tests and publishes a template using GitHub Actions.
The workflow:
- Validates the Terraform template.
- Pushes the template to Coder without activating it.
- Tests the template by creating a workspace.
- Promotes the template version to active upon successful workspace creation.
Workflow File
Save the following workflow file as .github/workflows/publish-template.yaml in your repository:
name: Test and Publish Coder Template
on:
push:
branches:
- main
workflow_dispatch:
jobs:
test-and-publish:
runs-on: ubuntu-latest
env:
TEMPLATE_NAME: "my-template"
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Terraform
uses: hashicorp/setup-terraform@v2
with:
terraform_version: latest
- name: Set up Coder CLI
uses: coder/setup-action@v1
with:
access_url: "https://coder.example.com"
coder_session_token: ${{ secrets.CODER_SESSION_TOKEN }}
- name: Validate Terraform template
run: terraform validate
- name: Get short commit SHA to use as template version name
id: name
run: echo "version_name=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
- name: Get latest commit title to use as template version description
id: message
run:
echo "pr_title=$(git log --format=%s -n 1 ${{ github.sha }})" >>
$GITHUB_OUTPUT
- name: Push template to Coder
run: |
coder templates push $TEMPLATE_NAME --activate=false --name ${{ steps.name.outputs.version_name }} --message "${{ steps.message.outputs.pr_title }}" --yes
- name: Create a test workspace and run some example commands
run: |
coder create -t $TEMPLATE_NAME --template-version ${{ steps.name.outputs.version_name }} test-${{ steps.name.outputs.version_name }} --yes
# run some example commands
coder ssh test-${{ steps.name.outputs.version_name }} -- make build
- name: Delete the test workspace
if: always()
run: coder delete test-${{ steps.name.outputs.version_name }} --yes
- name: Promote template version
if: success()
run: |
coder template version promote --template=$TEMPLATE_NAME --template-version=${{ steps.name.outputs.version_name }}