Templates
Overview of system templates and workspace templates
CollabOps provides two types of templates:
System Templates — Built-in templates provided by CollabOps. Referenced at the Step level with uses.
Workspace Templates — Custom templates created within your workspace. Referenced at the Job level with include.
At a glance
| System template | Workspace template | |
|---|---|---|
| Provided by | CollabOps (built-in, fixed) | You, in your own workspace |
| Keyword | uses | include |
| Reference level | Step | Job |
| Format | collabops/\{name\}@\{version\} | \{workspace\}/\{repo\}/\{template_name\} |
| Example | collabops/checkout@v2 | my-workspace/infra-repo/deploy-k8s |
| Versioning | Yes (pinned tag, e.g. @v2) | None (latest commit on that repo) |
| When to use | Single actions: checkout, build, push… | Reusing a whole Job (image, env, steps) |
Common mistake — Do not put your own workspace/repo in a system template's uses. ❌ uses: my-workspace/my-repo@v1 will not resolve. The owner of a system template is always collabops (e.g., collabops/checkout@v2). To reuse a template defined in your own workspace, use include at the Job level, not uses at the Step level.
Two Reference Mechanisms
System Templates (uses)
Referenced at the Step level with uses. Defines a single execution unit (Step).
jobs:
build:
steps:
# Reference a system template in a Step (owner is always 'collabops')
- name: checkout
uses: "collabops/checkout@v2"
with:
repo-url: "https://<collabops-host>/<workspace>/<repository>.git"Format: collabops/\{name\}@\{version\}
Owner is always collabops — your workspace or repo name does not go here.
Pass input parameters with with
run and uses are mutually exclusive. You cannot use both in the same Step.
Workspace Templates (include)
Referenced at the Job level with include. Defines an entire Job configuration including image, environment variables, and step list.
jobs:
deploy:
# Reference a workspace template in a Job (your own workspace/repo goes here)
include: "my-workspace/infra-repo/deploy-k8s"
env:
CLUSTER_NAME: production
APP_NAME: my-appFormat: \{workspace\}/\{repo\}/\{template_name\}
Override template environment variables with Job env
No versioning (uses latest commit)