Keep Coder templates up to date

Coder Templates 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.

It’s easy to update an existing template. You can make local changes to the template directly and then push the changes to your 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.

Use the Coder CLI to push changes to the Coder template

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. Push the changes 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.

There are multiple ways to automate templates updates, like our REST API, CLI and terraform-provider-coderd. Here we describe how to push template updates using the setup-coder action which installs and authenticates the Coder CLI with your Coder server:

1. Create a new repository for your template(s).
2. In your repository, create a new workflow called push-to-coder.yml. 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.

4. Use the setup-coder action from GitHub marketplace to create the workflow:

   coder tokens create --lifetime 8760h0m0s
   

5. Add the following steps to the push-to-coder.yaml 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@v4
                   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: Setup Coder
                   uses: coder/setup-action@v1
                   with:
                       access_url: 'https://coder.example.com'
                       coder_session_token: ${{ secrets.CODER_SESSION_TOKEN }}
   
               - name: "Push template"
                   run: |
                       coder templates push <template-name> /
                       --directory ./<template-directory> /
                       --name ${{ steps.vars.outputs.sha_short }} /
                       --yes
   

6. Push the changes to the Git repository. This will trigger the workflow and push the changes to the template to the Coder server.

See Coder's setup-coder on GitHub marketplace.

See Coder's dogfood example workflow.

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