Skip to content

Commit 172e7b8

Browse files
matifalimatifali
committed
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.
1 parent 365ce67 commit 172e7b8

File tree

2 files changed

+111
-0
lines changed

2 files changed

+111
-0
lines changed

‎docs/admin/templates/managing-templates/change-management.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,14 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
8888
--name=$CODER_TEMPLATE_VERSION # Version name is optional
8989
```
9090

91+
You can also use the [coder/setup-action](https://github.com/coder/setup-coder)
92+
GitHub Action to install the Coder CLI and push new template versions.
93+
94+
## Testing and Publishing Coder Templates in CI/CD
95+
96+
See our [testing templates](../../../tutorials/testing-templates.md) tutorial
97+
for an example of how to test and publish Coder templates in a CI/CD pipeline.
98+
9199
### Next steps
92100

93101
- [Coder CLI Reference](../../../reference/cli/templates.md)

‎docs/tutorials/testing-templates.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Testing and Publishing Coder Templates in CI/CD
2+
3+
<div>
4+
<a href="https://github.com/matifali" style="text-decoration: none; color: inherit;">
5+
<span style="vertical-align:middle;">Muhammad Atif Ali</span>
6+
<img src="https://github.com/matifali.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
7+
</a>
8+
</div>
9+
November 15, 2024
10+
11+
---
12+
13+
## Overview
14+
15+
This guide demonstrates how to test and publish Coder templates in a Continuous
16+
Integration (CI) pipeline using the
17+
[coder/setup-action](https://github.com/coder/setup-coder). This workflow
18+
ensures your templates are validated, tested, and promoted seamlessly.
19+
20+
## Prerequisites
21+
22+
Before proceeding, ensure the following:
23+
24+
- **Coder CLI** is installed and configured in your environment.
25+
- **Terraform CLI** is installed and available in your CI environment.
26+
- Access to your **Coder instance** with the appropriate
27+
[permissions](../admin/users/groups-roles#roles).
28+
29+
## Example GitHub Action Workflow
30+
31+
Below is an example workflow for testing and publishing a template using GitHub
32+
Actions. The workflow first validates the Terraform template, pushes the
33+
template to Coder without activating it, tests the template by creating a
34+
workspace, and then promotes the template version to active upon successful
35+
workspace creation.
36+
37+
### Step-by-Step Process
38+
39+
1. **Validate the Terraform template.**
40+
2. **Push the template to Coder without activating it.**
41+
3. **Test the template by creating a workspace.**
42+
4. **Promote the template version to active upon successful workspace
43+
creation.**
44+
45+
### Workflow File
46+
47+
Save the following workflow file as `.github/workflows/template-ci.yaml` in your
48+
repository:
49+
50+
```yaml
51+
name: Test and Publish Coder Template
52+
53+
on:
54+
push:
55+
branches:
56+
- main
57+
workflow_dispatch:
58+
59+
jobs:
60+
test-and-publish:
61+
runs-on: ubuntu-latest
62+
env:
63+
TEMPLATE_NAME: "my-template"
64+
steps:
65+
- name: Checkout repository
66+
uses: actions/checkout@v4
67+
68+
- name: Set up Terraform
69+
uses: hashicorp/setup-terraform@v2
70+
with:
71+
terraform_version: latest
72+
73+
- name: Set up Coder CLI
74+
uses: coder/setup-action@v1
75+
with:
76+
access_url: 'https://coder.example.com'
77+
coder_session_token: ${{ secrets.CODER_SESSION_TOKEN }}
78+
79+
- name: Validate Terraform template
80+
run: terraform validate
81+
82+
- name: Get short commit SHA to use as template version name
83+
id: name
84+
run: echo "version_name=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
85+
86+
- name: Get latest commit title to use as template version description
87+
id: message
88+
run: echo "pr_title=$(git log --format=%s -n 1 ${{ github.sha }})" >> $GITHUB_OUTPUT
89+
90+
- name: Push template to Coder
91+
run: |
92+
coder templates push $TEMPLATE_NAME --activate=false --name ${{ steps.name.outputs.version_name }} --message ${{ steps.message.outputs.pr_title }} --yes
93+
94+
- name: Create a test workspace
95+
run: |
96+
coder create -t $TEMPLATE_NAME --template-version ${{ steps.name.outputs.version_name }} --yes
97+
98+
- name: Promote template version
99+
if: success()
100+
run: |
101+
coder template version promote --template=$TEMPLATE_NAME --template-version=${{ steps.name.outputs.version_name }} --yes
102+
103+
```

0 commit comments

Comments
 (0)