docs: add guide for CI/CD template testing

Introduce a new tutorial outlining the process for testing and publishing Coder templates within a CI/CD pipeline using GitHub Actions. This guide includes prerequisites, a comprehensive workflow example, and detailed steps for template validation and deployment.
coder · matifali · Nov 20, 2024 · Nov 15, 2024 · Nov 15, 2024 · Nov 18, 2024
commit 172e7b826ac771bf2ed4c3452e61fef498e47cc0
diff --git a/docs/admin/templates/managing-templates/change-management.md b/docs/admin/templates/managing-templates/change-management.md
@@ -88,6 +88,14 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
     --name=$CODER_TEMPLATE_VERSION # Version name is optional
 ```
 
+You can also use the [coder/setup-action](https://github.com/coder/setup-coder)
+GitHub Action to install the Coder CLI and push new template versions.
+
+## Testing and Publishing Coder Templates in CI/CD
+
+See our [testing templates](../../../tutorials/testing-templates.md) tutorial
+for an example of how to test and publish Coder templates in a CI/CD pipeline.
+
 ### Next steps
 
 - [Coder CLI Reference](../../../reference/cli/templates.md)

diff --git a/docs/tutorials/testing-templates.md b/docs/tutorials/testing-templates.md
@@ -0,0 +1,103 @@
+# Testing and Publishing Coder Templates in CI/CD
+
+<div>
+  <a href="https://github.com/matifali" style="text-decoration: none; color: inherit;">
+    <span style="vertical-align:middle;">Muhammad Atif Ali</span>
+    <img src="https://github.com/matifali.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
+  </a>
+</div>
+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](https://github.com/coder/setup-coder). This workflow
+ensures your templates are validated, tested, and promoted seamlessly.
+
+## Prerequisites
+
+Before proceeding, ensure the following:
+
+- **Coder CLI** is installed and configured in your environment.
+- **Terraform CLI** is installed and available in your CI environment.
+- Access to your **Coder instance** with the appropriate
+  [permissions](../admin/users/groups-roles#roles).
+
+## Example GitHub Action Workflow
+
+Below is an example workflow for testing and publishing a template using GitHub
+Actions. The workflow first validates the Terraform template, pushes the
+template to Coder without activating it, tests the template by creating a
+workspace, and then promotes the template version to active upon successful
+workspace creation.
+
+### Step-by-Step Process
+
+1. **Validate the Terraform template.**
+2. **Push the template to Coder without activating it.**
+3. **Test the template by creating a workspace.**
+4. **Promote the template version to active upon successful workspace
+   creation.**
+
+### Workflow File
+
+Save the following workflow file as `.github/workflows/template-ci.yaml` in your
+repository:
+
+```yaml
+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
+        run: |
+          coder create -t $TEMPLATE_NAME --template-version ${{ 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 }} --yes
+
+```