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 — pick a pin level: @v1 / @v1.2 / @v1.2.3 | 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.
Pinning a version
A system template lets you choose, via @\{version\}, which point-in-time behavior to pin to. Three levels are supported.
| Format | Meaning | Auto-update |
|---|---|---|
@v1 | Pin major | Latest compatible minor & patch |
@v1.2 | Pin minor | Latest patch only (minor stays fixed) |
@v1.2.3 | Pin exact version | None — immutable once published |
An exact version (@v1.2.3) never changes once published (immutable). Prefer it for production pipelines where reproducibility matters. @v1 and @v1.2 follow the latest within their compatible range, so you receive security and bug-fix patches without editing your workflow.
When the major changes (v1 → v2), there may be breaking changes, so it is not picked up automatically. Minor and patch updates are backward compatible.
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)