Skip to main content

Create a Workspace Template

Last updated on

With workspace templates, you standardize workspace configurations across your projects by predefining variables, settings, and other workspace options. Templates streamline setup, keep workspaces consistent, and let platform teams lock specific settings so they cannot drift after a workspace is linked.

What you will learn​

  • How to create, edit, and apply a workspace template.
  • The difference between linking a workspace to a template and copying a template.
  • Which workspace settings a template can lock.
  • How Harness behaves when you update a locked field on a linked workspace.
  • How to change the template version a workspace uses.

Before you begin​

  • Template permissions: Permission to create and edit account-level or project-level templates. Go to RBAC in Harness to configure roles.
  • Target scope: Access to an account or project where you apply the template.
  • Workspace basics: Familiarity with workspace setup. Go to the IaCM get started guide to review the workspace creation flow.

Use a template or copy a template​

When you apply a workspace template, you choose how the new workspace relates to the template.

  • Use Template: The workspace stays linked to the template and reflects future template changes. Settings the template locks are enforced on the workspace.
  • Copy Template: Harness creates a one-time copy of the template as it exists at that moment. The workspace is independent, no settings are locked, and later template changes do not apply.
tip

Choose Use Template when you want central control and ongoing consistency. Choose Copy Template when you want a starting point that teams can edit freely.

Configure workspace templates​

To configure workspace templates and standardize your workspace setups, follow this interactive guide.

Locked fields​

When you build a template, you can lock individual settings. A locked setting is enforced on every workspace that links to the template through Use Template. Locking keeps critical configuration consistent and prevents workspace owners from changing values your platform team controls.

Locked settings apply only to linked workspaces. A workspace created with Copy Template has no locked settings, because it is an independent copy with no ongoing association.

You can lock the following template settings.

  • Provisioner: Provisioner type, provisioner version, and the provider connector.
  • Repository: Repository name, connector, path, and the Git fetch type with its branch, commit, or tag value.
  • Cost estimation: Whether cost estimation is enabled, and the budget.
  • Terraform and environment variables: The value of any locked variable. Template-provided variables also cannot be removed from a linked workspace.
  • Terraform variable files: Locked variable files cannot be removed.
  • Provider connectors: Locked provider connectors cannot be removed.
  • Default pipelines: The plan, apply, destroy, and drift pipelines, for project-level templates.
  • Required tags: Tags the template requires must remain on the workspace.

Settings that the template does not lock remain editable on each linked workspace.

Update a linked workspace​

Harness validates every update to a linked workspace against the template version the workspace currently uses. When an update keeps the locked values, the update succeeds. When an update changes a locked value, removes a locked variable file or provider connector, removes a template-provided variable, or drops a required tag, Harness rejects the entire update and returns a validation error that lists the conflicting fields. Harness does not silently strip or ignore the change, so the workspace always matches the template.

To change a locked value, update the value in the template, or move the workspace to a template version that allows the change. To change a value the template does not lock, edit the workspace as usual.

info

Changing the workspace fields and changing the template version are separate operations. The workspace update request does not carry a template version, so you cannot edit field values and move to a new template version in the same request. Update the fields first, or change the template version first, then make the other change.

Change the template version​

A linked workspace points to a specific template version. When you move the workspace to a different version, Harness reconciles the workspace against the new version and overwrites any locked settings with the values from that version. Fields the new version does not lock are left as they are.

Review the changes before you apply them so you know which locked settings will change. Go to Workspace statuses to confirm the workspace returns to an active state after reconciliation.

Troubleshooting​

Updating an IaCM workspace fails with a validation error that lists locked fields from the associated workspace template

The workspace is linked to a template that locks one or more of the fields you changed. Revert the locked fields to the template values, or update the value in the template, then retry the workspace update.

A change made to an IaCM workspace template is not reflected on a workspace created from that template

The workspace was created with Copy Template, which is a one-time copy with no ongoing link. Recreate the workspace with Use Template, or apply the change to the workspace directly.

Next steps​

Workspace templates standardize setup, enforce locked settings, and reduce the risk of misconfiguration across projects.