Keeping Templates up to date

Muhammad Atif Ali

 on May 25th, 2023

Updated on August 18th, 2023

Keeping Coder templates up to date

Templates in Coder help keep each developer's workspace consistent. When a new template version is created (e.g. with a newer version of Java or more CPU cores), all developers are notified to update their workspaces.

Updating an existing Coder template is easy. You can make changes to the template directly locally and then push the changes to Coder server in multiple ways.

To keep your Coder templates up to date, you need to push the changes to Coder server. A user with a template-admin or owner role can update templates.

Using the Coder CLI

You can use the Coder CLI to push the changes to the template to the Coder server. This is the easiest way to update the template.

1. Install the Coder CLI. See Installing the Coder CLI for more information.
2. Run the following command to push the changes to the template to the Coder server.

coder templates push <template-name>

This will push the changes to the template to the Coder server, assign a random name to the template, and create a new template version. All users will then see the Update button on their workspace.

Using CI/CD

You can also use CI/CD to push the changes to the template to the Coder server. This is useful if you want to automate the process of updating the template. This is the preferred method if you have a version control system for your templates and want your developers to update the template by creating a pull request.

1. Create a new repository for your template(s).
2. Create a new workflow in your repository. See Creating a workflow file for more information.
3. Create a new personal access token with the template-admin or owner role. and add it to the repository action secrets with the name CODER_SESSION_TOKEN.

coder tokens create --lifetime 8760h0m0s

1. Add the following steps to the workflow.

name: Push template to coder server

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy_template:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
      - name: Get short commit SHA # to use as template version name
        id: vars
        run: echo "::set-output name=sha_short::$(git rev-parse --short HEAD)"
      - name: "Install latest Coder"
        run: |
          curl -L https://coder.com/install.sh | sh
      - name: "Push template"
        run: |
          coder templates push <template-name> /--directory ./<template-directory> /
          --name ${{ steps.vars.outputs.sha_short }} /
          --yes
        env:
          # Consumed by Coder CLI
          CODER_URL: https://coder.example.com
          CODER_SESSION_TOKEN: ${{ secrets.CODER_SESSION_TOKEN }}

or you can use the Update Coder Template action from the GitHub marketplace.

name: Update Coder Template

on:
  push:
    branches:
      - main

jobs:
    update:
        runs-on: ubuntu-latest
        steps:
        - name: Checkout
          uses: actions/checkout@v3
        - name: Get latest commit hash
          id: latest_commit
          run: echo "hash=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
        - name: Get commit title
           id: commit_title
           run: echo "title=$(git log -1 --pretty=%B)" >> $GITHUB_OUTPUT


        - name: Update Coder Template
            uses: matifali/update-coder-template@v3
            with:
                id: "my-template"
                dir: "my-template"
                url: "https://coder.example.com"
                name: "${{ steps.latest_commit.outputs.hash }}"
                message: "${{ steps.commit_title.outputs.title }}"
                coder_session_token: ${{ secrets.CODER_SESSION_TOKEN }}

1. Push the changes to the template to the git repository. This will trigger the workflow and push the changes to the template to the Coder server.

See Coder's dogfood example workflow here.

See a community action Update Coder Template to automatically update templates.