
The word "template" means two different things in Argo Workflows, and that is the first source of confusion for new users. Inside a workflow, a template is a single unit of work such as a container or a DAG. At the cluster level, a WorkflowTemplate is a stored, reusable workflow definition. This guide focuses on the second meaning — how to build a library of reusable workflow definitions that teams can submit, compose and version safely — while clarifying how both meanings connect.
Why Reusable Templates Matter
Without stored templates, every pipeline is a standalone YAML file. Teams copy and paste the same "build image" or "notify Slack" logic into dozens of workflows, and every fix must be applied everywhere. WorkflowTemplates solve this in three ways:
- Single source of truth: shared steps live in one object, so fixes and upgrades happen once.
- Self-service submission: users can launch a stored template from the UI or CLI with a form for its parameters, without touching YAML.
- Composition: workflows call individual templates from a WorkflowTemplate with
templateRef, assembling pipelines from tested building blocks.
The Template Kinds Compared
| Kind | Scope | Typical use |
|---|---|---|
Workflow |
One execution | A single run, created by a person, a CronWorkflow or an event |
WorkflowTemplate |
Namespace | Reusable pipelines and steps owned by a team |
ClusterWorkflowTemplate |
Cluster | Organisation-wide building blocks shared across namespaces |
CronWorkflow |
Namespace | A schedule that creates Workflows from a spec or template |
Creating a WorkflowTemplate
A WorkflowTemplate uses the same spec as a Workflow. The only structural differences are the kind and the use of a fixed name:
apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
name: build-and-push
namespace: ci
annotations:
workflows.argoproj.io/description: Build a container image with Kaniko and push it
spec:
entrypoint: main
serviceAccountName: ci-builder
arguments:
parameters:
- name: repo
- name: image
- name: tag
value: latest-dev
templates:
- name: main
steps:
- - name: build
template: kaniko
arguments:
parameters:
- {name: repo, value: "{{workflow.parameters.repo}}"}
- {name: destination, value: "{{workflow.parameters.image}}:{{workflow.parameters.tag}}"}
- name: kaniko
inputs:
parameters:
- name: repo
- name: destination
container:
image: gcr.io/kaniko-project/executor:v1.23.2
args:
- "--context={{inputs.parameters.repo}}"
- "--destination={{inputs.parameters.destination}}"
resources:
requests: {cpu: "1", memory: 2Gi}
Apply it like any other resource:
kubectl apply -n ci -f build-and-push.yaml
argo template list -n ci
The argo template create command also works, and argo template lint validates the file first.
Three Ways to Use a WorkflowTemplate
1. Submit It Directly
argo submit -n ci --from workflowtemplate/build-and-push \
-p repo=git://github.com/example/api.git \
-p image=registry.example.com/api \
-p tag=1.9.0 --watch
The CLI creates a new Workflow whose workflowTemplateRef points at the template. The UI offers the same with a "Submit" button and a parameter form.
2. Reference the Whole Template From a Workflow
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: api-build-
namespace: ci
spec:
workflowTemplateRef:
name: build-and-push
arguments:
parameters:
- {name: repo, value: "git://github.com/example/api.git"}
- {name: image, value: registry.example.com/api}
The workflow inherits the template's entire spec. Fields set in the Workflow, such as arguments, labels or activeDeadlineSeconds, are merged on top. This is the pattern used by CronWorkflows and by Argo Events sensors to launch stored pipelines.
3. Call a Single Template With templateRef
- name: release
steps:
- - name: image
templateRef:
name: build-and-push
template: kaniko
arguments:
parameters:
- {name: repo, value: "git://github.com/example/web.git"}
- {name: destination, value: "registry.example.com/web:2.0.0"}
templateRef borrows one named template, here kaniko, from the stored object. The calling workflow supplies arguments and runs the step as if it were defined locally. This is the most powerful composition mechanism because it lets you build new pipelines from proven parts.
ClusterWorkflowTemplates
When a building block is useful to every team — security scanning, notifications, artifact promotion — publish it once at cluster scope:
apiVersion: argoproj.io/v1alpha1
kind: ClusterWorkflowTemplate
metadata:
name: notify
spec:
templates:
- name: slack
inputs:
parameters:
- name: text
container:
image: curlimages/curl:8.10.1
command: [sh, -c]
args:
- >
curl -fsS -X POST -H 'Content-Type: application/json'
--data "{\"text\": \"{{inputs.parameters.text}}\"}" "$WEBHOOK"
env:
- name: WEBHOOK
valueFrom:
secretKeyRef: {name: slack-webhook, key: url}
Reference it with clusterScope: true:
templateRef:
name: notify
template: slack
clusterScope: true
Note that the Secret slack-webhook is resolved in the namespace where the workflow runs, not where the template was defined, because ClusterWorkflowTemplates have no namespace. Each consuming namespace must therefore provide its own copy of the secret, which is actually a useful security property: teams cannot read each other's credentials.
Designing Template Parameters
Good parameters make templates easy and safe to use:
- Give sensible defaults for optional values so most callers pass only what matters.
- Use
enumfor constrained values such as environments; the UI renders a drop-down. - Add descriptions with the
descriptionfield on parameters so the submit form explains each one. - Validate early. A first step that checks parameter combinations fails fast with a clear message instead of failing deep in the pipeline.
- Avoid secret parameters. Pass the name of a Secret, not its value.
arguments:
parameters:
- name: environment
value: staging
enum: [dev, staging, production]
description: Target environment for the deployment
Versioning Strategies
Because templates are referenced by name, changing a template changes every pipeline that uses it. Choose a strategy deliberately.
Strategy A: Version in the Name
Publish build-and-push-v1 and build-and-push-v2 side by side. Consumers upgrade explicitly by changing the reference. This is the safest option for widely shared ClusterWorkflowTemplates.
Strategy B: Single Name, Git-Controlled Changes
Keep one name and treat every change like an API change: backwards-compatible additions only, reviewed in pull requests, deployed through Argo CD. This works well for team-owned templates with few consumers.
Strategy C: Semantic Labels
Label templates with a version and a stability channel, and document which channel each consuming pipeline should use. It requires discipline but keeps names stable.
Whatever you choose, remember that a running workflow resolves template references when it starts and stores the result in its status, so changing a template does not affect workflows that are already running.
Building a Template Library: A Practical Layout
Most organisations end up with three layers of templates. Planning for them from the start keeps the library tidy as it grows.
Layer 1: Primitive Building Blocks
These are small, single-purpose templates published as ClusterWorkflowTemplates by the platform team: send a notification, build an image, scan an image, copy files between buckets, run a database migration, wait for a Kubernetes resource. Each one has a narrow interface, clear parameters and strong tests. Application teams never edit them; they only call them with templateRef.
Layer 2: Team Pipelines
Each team composes primitives into WorkflowTemplates in its own namespace: "build, test and publish the API", "refresh the analytics mart", "retrain the recommendation model". These templates encode the team's process and usually have an entrypoint so they can be submitted directly or scheduled.
Layer 3: Triggers
CronWorkflows, Argo Events sensors and CI jobs sit on top and decide when team pipelines run. They contain almost no logic of their own — just a schedule or event, a workflowTemplateRef and the arguments for that particular invocation.
This layering gives each group a clear responsibility. The platform team owns reliability and security of primitives, application teams own their process, and triggers stay trivial to review.
Testing Templates Before You Publish Them
A broken shared template can break dozens of pipelines at once, so test templates as carefully as application code:
- Lint in CI.
argo template lintvalidates structure and references on every pull request. - Unit-test the container logic. The image a template runs should have its own tests independent of Argo.
- Run an integration workflow. Apply the changed template to a test namespace and submit a small workflow that calls it with representative parameters. Fail the pull request if that workflow fails.
- Check backwards compatibility. If existing consumers pass parameters that you renamed or removed, their next run will fail. Keep old parameters working, or publish a new version.
- Document changes. A short changelog in the template's annotations or repository helps consumers understand what changed and why.
Teams that adopt this routine rarely suffer surprise breakages from shared templates, even with hundreds of consumers.
Managing Templates With GitOps
Store templates in Git, one file per template, organised by namespace. Sync them with Argo CD or Flux. Add CI that runs argo lint on every pull request, and optionally submit changed templates to a test namespace with sample parameters. This gives you code review, an audit trail and instant rollback for pipeline changes — the same guarantees application code enjoys.
Workflow-Level Defaults in Templates
Everything you can put in a Workflow spec can also live in a WorkflowTemplate, and that makes templates an excellent place to encode operational standards. A team pipeline template can include activeDeadlineSeconds, ttlStrategy, podGC, labels for cost reporting, a default serviceAccountName, node selectors and an onExit notification. Every run created from the template inherits those settings automatically, so authors of individual runs cannot forget them.
When a Workflow references a template with workflowTemplateRef, fields set on the Workflow are merged over the template's spec. That lets a caller extend a deadline or add a label for a special run without editing the shared template. Be aware that merging works at field level: setting arguments.parameters on the Workflow supplies values for the template's parameters, but providing a completely different templates list is not supported when a template reference is used.
Template Naming Conventions
Clear names make a library discoverable. A few conventions that scale well:
- Use verbs for primitives:
build-image,scan-image,send-slack,copy-s3. - Use nouns for pipelines:
api-release,orders-etl,churn-model-training. - Add a version suffix only to templates consumed by many teams, as described above.
- Keep names inside a template short and descriptive, because they appear in node names and expressions.
Combined with description annotations, these conventions let new team members browse the template list in the UI and understand what is available without asking.
Security Considerations
- Templates run with the service account set in the template or calling workflow. Do not set powerful service accounts inside shared templates unless every consumer should have that power.
- The controller option
templateReferencing: Strictforces all workflows to use stored templates, which prevents users from submitting arbitrary inline YAML.Securemode additionally snapshots the template at submission so later edits cannot change a running workflow's behaviour. - Limit who can create or update ClusterWorkflowTemplates with RBAC; they affect every namespace.
Troubleshooting Templates
workflowtemplates.argoproj.io "x" not found— the template is in a different namespace. WorkflowTemplates are namespace-scoped; use a ClusterWorkflowTemplate for cross-namespace reuse.template x not found in workflow template y— thetemplatefield intemplateRefdoes not match a template name inside the stored object.- Missing parameter errors when submitting — required parameters without values must be supplied with
-p. - ClusterWorkflowTemplate reference fails —
clusterScope: trueis missing fromtemplateRef. - Changes not picked up — the workflow started before you applied the change; resubmit it.
Frequently Asked Questions
Can a WorkflowTemplate reference another WorkflowTemplate?
Yes. Templates can use templateRef to call templates from other stored objects, which lets you build layered libraries.
Can I run a ClusterWorkflowTemplate directly?
Yes, with argo submit --from clusterworkflowtemplate/<name>, provided you have permission in the target namespace.
Do WorkflowTemplates need an entrypoint?
Only if they will be submitted directly or referenced with workflowTemplateRef. Library templates used purely through templateRef can omit it.
How do I build templates quickly?
Use our Workflow Template Builder to assemble container and script templates visually and download valid YAML.
Key Takeaways
- WorkflowTemplates are namespace-scoped; ClusterWorkflowTemplates are shared across namespaces.
- Use
workflowTemplateRefto run a whole template andtemplateRefto borrow a single step. - Design parameters with defaults, enums and descriptions so the UI form is self-explanatory.
- Pick a versioning strategy before templates have many consumers.
- Lint, test and review template changes like application code.
- Restrict who can modify shared templates with RBAC and template referencing modes.
- Layer your library: platform primitives at cluster scope, team pipelines in namespaces, and thin triggers such as CronWorkflows and sensors on top. Document every template with a description annotation so the UI explains what it does.
Conclusion
WorkflowTemplates and ClusterWorkflowTemplates turn Argo Workflows into a platform of reusable building blocks. Define clear parameters, choose a versioning strategy, manage everything through Git and restrict who can change shared templates. Then schedule your stored pipelines with the CronWorkflow guide. A well-organised template library is one of the highest-leverage investments a platform team can make, because every improvement to a shared building block immediately benefits every pipeline that uses it, across every team in the organisation.



