Skip to content

Commit dcbcf67

Browse files
matifaliEdwardAngert
matifali
and
EdwardAngert
authored
docs: add guide for CI/CD template testing (coder#15528)
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
1 parent a518017 commit dcbcf67

File tree

3 files changed

+130
-2
lines changed

3 files changed

+130
-2
lines changed

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

+8-2
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,9 @@ For an example, see how we push our development image and template
6262

6363
## Coder CLI
6464

65-
You can also [install Coder](../../../install/cli.md) to automate pushing new
66-
template versions in CI/CD pipelines.
65+
You can [install Coder](../../../install/cli.md) CLI to automate pushing new
66+
template versions in CI/CD pipelines. For GitHub Actions, see our
67+
[setup-coder](https://github.com/coder/setup-coder) action.
6768

6869
```console
6970
# Install the Coder CLI
@@ -88,6 +89,11 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
8889
--name=$CODER_TEMPLATE_VERSION # Version name is optional
8990
```
9091

92+
## Testing and Publishing Coder Templates in CI/CD
93+
94+
See our [testing templates](../../../tutorials/testing-templates.md) tutorial
95+
for an example of how to test and publish Coder templates in a CI/CD pipeline.
96+
9197
### Next steps
9298

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

‎docs/manifest.json

+5
Original file line numberDiff line numberDiff line change
@@ -709,6 +709,11 @@
709709
"description": "Learn how to clone Git repositories in Coder",
710710
"path": "./tutorials/cloning-git-repositories.md"
711711
},
712+
{
713+
"title": "Test Templates Through CI/CD",
714+
"description": "Learn how to test and publish Coder templates in a CI/CD pipeline",
715+
"path": "./tutorials/testing-templates.md"
716+
},
712717
{
713718
"title": "Use Apache as a Reverse Proxy",
714719
"description": "Learn how to use Apache as a reverse proxy",

‎docs/tutorials/testing-templates.md

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Test and Publish Coder Templates Through 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+
- Install and configure Coder CLI in your environment.
23+
- Install Terraform CLI in your CI environment.
24+
- Create a [headless user](../admin/users/headless-auth.md) with the
25+
[user roles and permissions](../admin/users/groups-roles.md#roles) to manage
26+
templates and run workspaces.
27+
28+
## Creating the headless user
29+
30+
```shell
31+
coder users create \
32+
--username machine-user \
33+
--email machine-user@example.com \
34+
--login-type none
35+
36+
coder tokens create --user machine-user --lifetime 8760h
37+
# Copy the token and store it in a secret in your CI environment with the name `CODER_SESSION_TOKEN`
38+
```
39+
40+
## Example GitHub Action Workflow
41+
42+
This example workflow tests and publishes a template using GitHub Actions.
43+
44+
The workflow:
45+
46+
1. Validates the Terraform template.
47+
1. Pushes the template to Coder without activating it.
48+
1. Tests the template by creating a workspace.
49+
1. Promotes the template version to active upon successful workspace creation.
50+
51+
### Workflow File
52+
53+
Save the following workflow file as `.github/workflows/publish-template.yaml` in
54+
your repository:
55+
56+
```yaml
57+
name: Test and Publish Coder Template
58+
59+
on:
60+
push:
61+
branches:
62+
- main
63+
workflow_dispatch:
64+
65+
jobs:
66+
test-and-publish:
67+
runs-on: ubuntu-latest
68+
env:
69+
TEMPLATE_NAME: "my-template"
70+
steps:
71+
- name: Checkout repository
72+
uses: actions/checkout@v4
73+
74+
- name: Set up Terraform
75+
uses: hashicorp/setup-terraform@v2
76+
with:
77+
terraform_version: latest
78+
79+
- name: Set up Coder CLI
80+
uses: coder/setup-action@v1
81+
with:
82+
access_url: "https://coder.example.com"
83+
coder_session_token: ${{ secrets.CODER_SESSION_TOKEN }}
84+
85+
- name: Validate Terraform template
86+
run: terraform validate
87+
88+
- name: Get short commit SHA to use as template version name
89+
id: name
90+
run: echo "version_name=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
91+
92+
- name: Get latest commit title to use as template version description
93+
id: message
94+
run:
95+
echo "pr_title=$(git log --format=%s -n 1 ${{ github.sha }})" >>
96+
$GITHUB_OUTPUT
97+
98+
- name: Push template to Coder
99+
run: |
100+
coder templates push $TEMPLATE_NAME --activate=false --name ${{ steps.name.outputs.version_name }} --message "${{ steps.message.outputs.pr_title }}" --yes
101+
102+
- name: Create a test workspace and run some example commands
103+
run: |
104+
coder create -t $TEMPLATE_NAME --template-version ${{ steps.name.outputs.version_name }} test-${{ steps.name.outputs.version_name }} --yes
105+
coder config-ssh --yes
106+
# run some example commands
107+
coder ssh test-${{ steps.name.outputs.version_name }} -- make build
108+
109+
- name: Delete the test workspace
110+
if: always()
111+
run: coder delete test-${{ steps.name.outputs.version_name }} --yes
112+
113+
- name: Promote template version
114+
if: success()
115+
run: |
116+
coder template version promote --template=$TEMPLATE_NAME --template-version=${{ steps.name.outputs.version_name }} --yes
117+
```

0 commit comments

Comments
 (0)