coder/docs/tutorials/testing-templates.md at main

mirror of https://github.com/coder/coder.git synced 2026-10-16 14:48:56 +08:00

Files

T

Nick Vigilante c58ac71ca3 docs(docs/tutorials): reformat to one sentence per line (#30703 )

Reformats the tutorials under `docs/tutorials` to one sentence per line,
as the [docs style
guide](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line)
requires. Hard-wrapped paragraphs are unwrapped and lines holding
several sentences are split, so a later edit to one sentence shows up as
a one-line diff.

Apart from the exception below, only whitespace inside paragraphs and
list items changes, and the rendered pages are the same. Comparing the
changed files against `main` word for word, ignoring whitespace and
blockquote `>` markers, finds differences only on the reworded lines.
`git diff --word-diff` is easier to read than the line diff.

9 lines that already contained an em or en dash were reworded by hand,
because `lint/emdash` treats every reflowed line as newly added. Each
uses a parenthetical, a separate sentence, or a colon after a lead-in.
Dashes on lines the reflow did not touch are left alone. The two reverse
proxy tutorials also write `*.coder.example.com` in backticks instead of
escaping the asterisk, which the formatter would otherwise drop.

Applied with an in-progress formatter, limited to pages listed in
`docs/manifest.json` and excluding generated reference docs. This is one
of a batch of PRs that split the docs by area (19 files changed, 656
insertions(+), 1265 deletions(-)).

---
🤖 Built with AI assistance.

2026-10-15 11:24:40 -04:00

4.1 KiB

Raw Permalink Blame History

title

title
Test and publish Coder templates through CI/CD

Muhammad Atif Ali

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 OSS deployments, use a regular account with password, GitHub, or 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 }}

4.1 KiB Raw Permalink Blame History