Workspace Templates

Workspace templates let you define reusable Job configurations that your team uses frequently. Push template files to a Git repository and they are automatically registered. Reference them in Workflows using include.

Workspace templates are included at the Job level. This is a different mechanism from step-level uses (system templates).

Differences from System Templates

Aspect	System Templates	Workspace Templates
Scope	Shared globally (built-in)	Workspace only
Reference	Step-level `uses: "collabops/name@version"`	Job-level `include: "workspace/repo/name@version"`
Unit	Step (single execution unit)	Job (includes image, env, steps)
Versioning	`@version` specified	`@version` specified (defaults to `v1` if omitted)
Registration	Provided by CollabOps	Automatic on git push

Registration

Add template files under the .collabops/template/ directory in your Git repository and push to register automatically. Templates are organized by \{name\}/\{version\}/.

.collabops/
  template/
    deploy-k8s/
      v1/
        template.yml
      v2/
        template.yml
    build-image/
      v1/
        template.yml

Each template must be located at .collabops/template/{template-name}/{version}/template.yml. The file must be named exactly template.yml, and a version directory (e.g., v1) is required.

Templates are automatically registered when changes under .collabops/template/ are detected on push.

Deleting a template file and pushing automatically unregisters it.

If both Workflow files and templates change in the same push, template registration completes first before Workflow execution.

Versioning

You can maintain multiple versions (v1, v2, ...) of a template with the same name simultaneously.

Workflows can pin to a specific version with @version, so template changes don't affect existing Workflows.

A reference without a version (include: "ws/repo/name") resolves to v1.

template.yml Structure

Workspace templates define a Job configuration. They follow the same structure as a Workflow Job.

# Template metadata
name: deploy-k8s
description: "Deploy to a Kubernetes cluster."

# Job configuration
job:
  # Default container image
  image: "bitnami/kubectl:latest"

  # Environment variables
  env:
    KUBECONFIG: /workspace/.kube/config

  # Step list
  steps:
    - name: setup-context
      run: |
        kubectl config use-context $CLUSTER_NAME

    - name: deploy
      run: |
        kubectl set image deployment/$APP_NAME \
          app=$IMAGE_TAG \
          -n $NAMESPACE
        kubectl rollout status deployment/$APP_NAME \
          -n $NAMESPACE \
          --timeout=300s

  # Auxiliary services (if needed)
  services:
    - docker

Template Schema

Field	Required	Type	Description
`name`	YES	string	Template name
`description`	YES	string	Template description
`job`	YES	object	Job configuration
`job.image`	NO	string	Default container image
`job.env`	NO	object	Job-level environment variables
`job.steps`	YES	list	Step list (at least 1)
`job.services`	NO	list	Auxiliary services

Step Schema

Template steps follow the same structure as Workflow steps.

Field	Required	Type	Description
`name`	YES	string	Step name
`run`	NO	string	Shell command to execute
`image`	NO	string	Per-step container image (overrides job.image)
`env`	NO	object	Step-level environment variables
`uses`	NO	string	System template reference (`collabops/name@version`)
`with`	NO	object	System template input parameters

Template steps can also reference system templates via uses. Include resolution runs first, followed by system template expansion.

Using in Workflows

Workspace templates are referenced using the include field at the Job level.

Reference Format

include: "{workspace}/{repo}/{template_name}@{version}"

\{workspace\}: Workspace name

\{repo\}: Repository where the template is registered

\{template_name\}: Directory name under .collabops/template/

\{version\}: Template version (e.g., v1, v2). Defaults to v1 if omitted.

# Explicit version
include: "my-workspace/infra-repo/deploy-k8s@v1"

# Omitted version → resolves to v1
include: "my-workspace/infra-repo/deploy-k8s"

# Different version
include: "my-workspace/infra-repo/deploy-k8s@v2"

Basic Usage

name: deploy-workflow

triggers:
  push:
    branches: [main]

jobs:
  deploy:
    # Include workspace template (explicit version recommended)
    include: "my-workspace/infra-repo/deploy-k8s@v1"

    # Add/override environment variables at the Job level
    env:
      CLUSTER_NAME: production
      APP_NAME: my-app
      NAMESPACE: production
      IMAGE_TAG: my-app:latest

Include Merge Rules

When including a template, values defined directly on the Job take precedence over template values.

Field	Merge Rule
`image`	Job value > Template value
`env`	Job env overrides template env (on key conflict)
`steps`	Template steps are prepended, Job steps follow after
`services`	Union (duplicates removed)
`needs`	Job value retained
`if`	Job value retained
`phase`	Job value retained

Template Steps + Job Steps Combined

# template.yml steps:
#   - setup-context
#   - deploy

jobs:
  deploy:
    include: "my-workspace/infra-repo/deploy-k8s@v1"
    env:
      CLUSTER_NAME: production
    steps:
      # Template's setup-context and deploy run first
      # Steps below are appended after
      - name: notify
        uses: "collabops/slack-notify@v1"
        with:
          webhook-url: ${{ secrets.SLACK_WEBHOOK }}
          message: "Deploy complete"

Execution order: setup-context → deploy → notify

Example: Custom Deployment Template

1. Create Template File

Create .collabops/template/deploy-k8s/v1/template.yml in your repository:

name: deploy-k8s
description: "Deploy to a Kubernetes cluster."

job:
  image: "bitnami/kubectl:latest"
  env:
    DEPLOY_TIMEOUT: "300s"
  steps:
    # Checkout source code
    - name: checkout
      uses: "collabops/checkout@v2"
      with:
        repo-url: "https://<collabops-host>/<workspace>/<repository>.git"

    # kubectl deployment
    - name: deploy
      run: |
        kubectl set image deployment/$APP_NAME \
          app=$IMAGE_TAG \
          -n $NAMESPACE
        kubectl rollout status deployment/$APP_NAME \
          -n $NAMESPACE \
          --timeout=$DEPLOY_TIMEOUT

2. Use in Workflow

name: production-deploy

triggers:
  push:
    branches: [main]

jobs:
  deploy-staging:
    include: "my-workspace/infra-repo/deploy-k8s@v1"
    phase: deploy
    env:
      APP_NAME: my-app
      NAMESPACE: staging
      IMAGE_TAG: "my-app:${{ collabops.sha }}"

  deploy-production:
    include: "my-workspace/infra-repo/deploy-k8s@v1"
    needs: [deploy-staging]
    phase: deploy
    if: "collabops.ref == 'refs/heads/main'"
    env:
      APP_NAME: my-app
      NAMESPACE: production
      IMAGE_TAG: "my-app:${{ collabops.sha }}"
    steps:
      # Template steps (checkout + deploy) run first, then notification
      - name: notify
        uses: "collabops/slack-notify@v1"
        with:
          webhook-url: ${{ secrets.SLACK_WEBHOOK }}
          message: "Production deploy complete: ${{ collabops.sha }}"

Example: Organization-Standard Build Template (multi-module)

When dozens or hundreds of projects in an organization share a similar structure, a single workspace template lets all of them share the same build flow. The example below covers a Java/Spring multi-module (api/domain/common) build.

The platform team defines the standard build at .collabops/template/org-standard-build/v1/template.yml in some workspace repository.

name: org-standard-build
description: 조직 표준 Java/Spring multi-module 빌드
runs:
  image: maven:3.9-eclipse-temurin-17
  steps:
    - name: maven-verify
      run: |
        cd /workspace/source
        mvn -B -ntp verify

Each service project includes this template from its own pipeline.yaml.

name: build
triggers:
  push:
    branches: [main]
jobs:
  build:
    # Include the workspace standard build template — every project follows the same flow.
    include: "<workspace>/<template-repo>/org-standard-build@v1"
    # Override only project-specific env vars
    env:
      SERVICE_NAME: "my-api"

With this pattern, N projects share the same build policy. Build options (JDK version, Maven options, cache policy, etc.) are changed once in the template. The java-spring-boot-multimodule starter-workflow on Marketplace is a reference for the same multi-module build flow.

Using with Internal Git Servers (GitLab CE / Bitbucket Server)

Workspace templates are referenced by a collabops workspace identifier (workspace/repo/name@version), not by a git URL. When an internal GitLab CE / Bitbucket Server / Gitea repository is integrated into a collabops workspace, its .collabops/template/ directory is auto-registered and can be used the same way.

jobs:
  build:
    # workspace templates are referenced by their collabops workspace identifier.
    # When an internal GitLab CE / Bitbucket Server / Gitea repository is
    # integrated into the workspace, its .collabops/template/ directory is
    # auto-registered and can be included the same way.
    include: "platform-team/build-templates/org-standard-build@v1"
    #          └ workspace slug    └ repo slug         └ template name @ version

In air-gapped environments, includes from external marketplaces (e.g. external registries like GitHub Actions) do not work. Only templates registered inside the workspace are reachable — internal git integration is the prerequisite.

Version Management and Tracking Impacted Projects

Templates are released as major versions like @v1, @v2. Publishing a new version does not affect existing projects until they explicitly upgrade — nothing breaks all at once.

# Release a new version (v2) — existing projects stay on v1 until they explicitly upgrade
jobs:
  build:
    include: "<workspace>/<template-repo>/org-standard-build@v2"   # ← changed from v1 to v2 explicitly

To find which projects include a particular template, check the 'Usage' section on the template detail page in the collabops UI, or search workspace-wide for the pattern include: "<workspace>/<template-repo>/<template-name>". Breaking changes should be released as a new major version (v2) rather than overwriting an existing version.

Overwriting the same version (v1) affects every project that includes it on the next build. Always release incompatible changes under a new major version.

Constraints

Workspace templates can only be used within the same workspace. Cross-workspace references are not supported.

The include format must be workspace/repo/template_name or workspace/repo/template_name@version (two / separators).

A reference without @version resolves to v1. Explicit version pinning is recommended.

Multiple versions of the same template can coexist, each under its own directory (v1/, v2/, ...).

A Job with include can have zero steps — the template provides the steps.

Workspace Templates

Table of Contents