Files
coder/docs/tutorials/testing-templates.md
T
Nick Vigilante 16551fd67f feat: enable Coder.AbbreviationFirstUse (#30878)
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.
2026-11-02 14:41:15 -05:00

4.2 KiB

title
title
Test and publish Coder templates through CI/CD
November 15, 2024

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 none is 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:

  1. Validates the Terraform template.
  2. Pushes the template to Coder without activating it.
  3. Tests the template by creating a workspace.
  4. 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 }}