coder · matifali · Nov 20, 2024 · Nov 15, 2024 · Nov 15, 2024 · Nov 18, 2024
diff --git a/docs/admin/templates/managing-templates/change-management.md b/docs/admin/templates/managing-templates/change-management.md
@@ -62,8 +62,9 @@ For an example, see how we push our development image and template
 
 ## Coder CLI
 
-You can also [install Coder](../../../install/cli.md) to automate pushing new
-template versions in CI/CD pipelines.
+You can [install Coder](../../../install/cli.md) CLI to automate pushing new
+template versions in CI/CD pipelines. For GitHub Actions, see our
+[setup-coder](https://github.com/coder/setup-coder) action.
 
 ```console
 # Install the Coder CLI
@@ -88,6 +89,11 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
     --name=$CODER_TEMPLATE_VERSION # Version name is optional
 ```
 
+## 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/manifest.json b/docs/manifest.json
@@ -709,6 +709,11 @@
 					"description": "Learn how to clone Git repositories in Coder",
 					"path": "./tutorials/cloning-git-repositories.md"
 				},
+				{
+					"title": "Test Templates Through CI/CD",
+					"description": "Learn how to test and publish Coder templates in a CI/CD pipeline",
+					"path": "./tutorials/testing-templates.md"
+				},
 				{
 					"title": "Use Apache as a Reverse Proxy",
 					"description": "Learn how to use Apache as a reverse proxy",

diff --git a/docs/tutorials/testing-templates.md b/docs/tutorials/testing-templates.md
@@ -0,0 +1,117 @@
+# Test and Publish Coder Templates Through 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
+
+- Install and configure Coder CLI in your environment.
+- Install Terraform CLI in your CI environment.
+- Create a [headless user](../admin/users/headless-auth.md) with the
+  [user roles and permissions](../admin/users/groups-roles.md#roles) to manage
+  templates and run workspaces.
+
+## Creating the headless user
+
+```shell
+coder users create \
+  --username machine-user \
+  --email machine-user@example.com \
+  --login-type none
+
+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.
+1. Pushes the template to Coder without activating it.
+1. Tests the template by creating a workspace.
+1. 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:
+
+```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 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
+          coder config-ssh --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 }} --yes
+```