From 172e7b826ac771bf2ed4c3452e61fef498e47cc0 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Fri, 15 Nov 2024 07:25:55 +0000 Subject: [PATCH 1/7] 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. --- .../managing-templates/change-management.md | 8 ++ docs/tutorials/testing-templates.md | 103 ++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 docs/tutorials/testing-templates.md diff --git a/docs/admin/templates/managing-templates/change-management.md b/docs/admin/templates/managing-templates/change-management.md index adff8d5120745..263b7571f2f59 100644 --- 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 new file mode 100644 index 0000000000000..bfd1830239680 --- /dev/null +++ b/docs/tutorials/testing-templates.md @@ -0,0 +1,103 @@ +# Testing and Publishing Coder Templates in 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](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 + +``` From c3913030bbfc93d141e1a98cf4581699fa35aa0d Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Fri, 15 Nov 2024 07:51:46 +0000 Subject: [PATCH 2/7] Update manifest to include testing templates guide Add a new entry in the documentation's manifest for a tutorial on testing and publishing Coder templates in a CI/CD pipeline. --- docs/manifest.json | 5 +++++ docs/tutorials/testing-templates.md | 21 +++++++++++---------- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 5c53ee05352dd..59dc6ddfcb05a 100644 --- 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": "Testing Templates", + "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 index bfd1830239680..e438559eceb71 100644 --- a/docs/tutorials/testing-templates.md +++ b/docs/tutorials/testing-templates.md @@ -24,7 +24,7 @@ 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). + [permissions](../admin/users/groups-roles.md#roles). ## Example GitHub Action Workflow @@ -44,8 +44,8 @@ workspace creation. ### Workflow File -Save the following workflow file as `.github/workflows/template-ci.yaml` in your -repository: +Save the following workflow file as `.github/workflows/publish-template.yaml` in +your repository: ```yaml name: Test and Publish Coder Template @@ -59,8 +59,8 @@ on: jobs: test-and-publish: runs-on: ubuntu-latest - env: - TEMPLATE_NAME: "my-template" + env: + TEMPLATE_NAME: "my-template" steps: - name: Checkout repository uses: actions/checkout@v4 @@ -73,8 +73,8 @@ jobs: - name: Set up Coder CLI uses: coder/setup-action@v1 with: - access_url: 'https://coder.example.com' - coder_session_token: ${{ secrets.CODER_SESSION_TOKEN }} + access_url: "https://coder.example.com" + coder_session_token: ${{ secrets.CODER_SESSION_TOKEN }} - name: Validate Terraform template run: terraform validate @@ -85,11 +85,13 @@ jobs: - 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 + 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 + 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: | @@ -99,5 +101,4 @@ jobs: if: success() run: | coder template version promote --template=$TEMPLATE_NAME --template-version=${{ steps.name.outputs.version_name }} --yes - ``` From 5569c9bdc52b51a0f9e0061e3003dafb99a13b12 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Mon, 18 Nov 2024 12:33:38 +0000 Subject: [PATCH 3/7] Enhance template testing with SSH command execution Add SSH configuration and example commands to test the workspace creation using the new template version. This ensures the template functions as expected before promotion. --- docs/tutorials/testing-templates.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/testing-templates.md b/docs/tutorials/testing-templates.md index e438559eceb71..9c2e48eff37b0 100644 --- a/docs/tutorials/testing-templates.md +++ b/docs/tutorials/testing-templates.md @@ -95,7 +95,13 @@ jobs: - name: Create a test workspace run: | - coder create -t $TEMPLATE_NAME --template-version ${{ steps.name.outputs.version_name }} --yes + coder create -t $TEMPLATE_NAME --template-version ${{ steps.name.outputs.version_name }} test-${{ steps.name.outputs.version_name }} --yes + + - name: Run some example commands + run: | + coder config-ssh --yes + # run some example commands + coder ssh test-${{ steps.name.outputs.version_name }} -- make build - name: Promote template version if: success() From c01ec95435880da7ce0e75d7d624949a8c929394 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 19 Nov 2024 15:40:43 +0500 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Edward Angert --- docs/manifest.json | 2 +- docs/tutorials/testing-templates.md | 29 +++++++++++------------------ 2 files changed, 12 insertions(+), 19 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 59dc6ddfcb05a..40b4a3ed02ad7 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -710,7 +710,7 @@ "path": "./tutorials/cloning-git-repositories.md" }, { - "title": "Testing Templates", + "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" }, diff --git a/docs/tutorials/testing-templates.md b/docs/tutorials/testing-templates.md index 9c2e48eff37b0..b9e74438f61a5 100644 --- a/docs/tutorials/testing-templates.md +++ b/docs/tutorials/testing-templates.md @@ -1,4 +1,4 @@ -# Testing and Publishing Coder Templates in CI/CD +# Test and Publish Coder Templates Through CI/CD
@@ -19,28 +19,21 @@ 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.md#roles). +- Install and configure Coder CLI in your environment. +- Install Terraform CLI in your CI environment. +- Configure [user roles and permissions](../admin/users/groups-roles.md#roles) for your Coder instance. ## 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. +This example workflow tests and publishes a template using GitHub +Actions. -### Step-by-Step Process +The workflow: -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.** +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 From d82b10cbb18851801f9058b7a77f873184395bd6 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 19 Nov 2024 13:06:18 +0000 Subject: [PATCH 5/7] Update template testing workflow to ensure cleanup --- docs/tutorials/testing-templates.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/testing-templates.md b/docs/tutorials/testing-templates.md index b9e74438f61a5..c3356b90b9332 100644 --- a/docs/tutorials/testing-templates.md +++ b/docs/tutorials/testing-templates.md @@ -86,16 +86,17 @@ jobs: 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 + - 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 - - - name: Run some example commands - run: | 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: | From b3ec9aa38f6c1d56ce210788dd5fa764eb13cd76 Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 19 Nov 2024 13:07:23 +0000 Subject: [PATCH 6/7] `make fmt` --- docs/tutorials/testing-templates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/testing-templates.md b/docs/tutorials/testing-templates.md index c3356b90b9332..c59d17163c8d6 100644 --- a/docs/tutorials/testing-templates.md +++ b/docs/tutorials/testing-templates.md @@ -21,12 +21,12 @@ ensures your templates are validated, tested, and promoted seamlessly. - Install and configure Coder CLI in your environment. - Install Terraform CLI in your CI environment. -- Configure [user roles and permissions](../admin/users/groups-roles.md#roles) for your Coder instance. +- Configure [user roles and permissions](../admin/users/groups-roles.md#roles) + for your Coder instance. ## Example GitHub Action Workflow -This example workflow tests and publishes a template using GitHub -Actions. +This example workflow tests and publishes a template using GitHub Actions. The workflow: From fa904b26b437f52c7b35cef8dadf842ab845deef Mon Sep 17 00:00:00 2001 From: Muhammad Atif Ali Date: Tue, 19 Nov 2024 13:09:07 +0000 Subject: [PATCH 7/7] docs: update CLI instructions and link setup-coder Clarified CLI installation instructions for pushing template versions and linked to the GitHub Actions setup-coder for automation. Removed redundant setup-action note and added details on creating a headless user for CI workflows. --- .../managing-templates/change-management.md | 8 +++----- docs/tutorials/testing-templates.md | 17 +++++++++++++++-- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/admin/templates/managing-templates/change-management.md b/docs/admin/templates/managing-templates/change-management.md index 263b7571f2f59..3df808babf0c3 100644 --- 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,9 +89,6 @@ 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 diff --git a/docs/tutorials/testing-templates.md b/docs/tutorials/testing-templates.md index c59d17163c8d6..c98852c7ae1f5 100644 --- a/docs/tutorials/testing-templates.md +++ b/docs/tutorials/testing-templates.md @@ -21,8 +21,21 @@ ensures your templates are validated, tested, and promoted seamlessly. - Install and configure Coder CLI in your environment. - Install Terraform CLI in your CI environment. -- Configure [user roles and permissions](../admin/users/groups-roles.md#roles) - for your Coder instance. +- 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