Overview
Overview and core concepts of CollabOps CI/CD pipelines
CollabOps Workflow DSL defines CI/CD pipelines using YAML-based syntax. This document describes the syntax, rules, constraints, and supported features needed to write Workflows.
Concepts
A CollabOps Workflow is organized in the following hierarchical structure:
Workflow
├── triggers # When to run (push, change_request, schedule, ...)
├── env # Global environment variables
└── jobs
├── job-a
│ ├── steps # List of commands executed sequentially
│ ├── env # Job-level environment variables
│ └── services # Auxiliary services (Docker, etc.)
└── job-b
├── needs: [job-a] # DAG dependency
└── stepsWorkflow — The top-level unit of a pipeline definition. It contains one or more Jobs and is triggered by execution conditions (triggers).
Job — An execution unit within a Workflow. Jobs run in parallel by default, and execution order can be defined using needs.
Step — The smallest unit executed sequentially within a Job. Defined using run (shell command) or uses (template reference).
Expression ($\{\{ \}\}) — An expression for referencing runtime values (environment variables, secrets, etc.).
Template — A reusable Step definition. Referenced with uses for use in workflows.
Repository checkout authentication — write repo-url as https://... and JobToken is injected automatically. Avoid registering a personal SSH key as a workspace variable. See the Authentication page for details.
Quick Start
Below is the screen for creating a Workflow file in a repository.
Workflows can be created directly in the remote repository or created locally and registered by pushing.
A minimal Workflow that checks out the source and builds when pushing to the main branch.
# Workflow name — displayed on the dashboard
name: my-first-workflow
# Trigger — runs on push to the main branch
triggers:
push:
branches: [main]
# Jobs — define tasks to execute
jobs:
build:
steps:
# 1. Checkout source code (HTTPS — JobToken injected automatically)
- name: checkout
uses: "collabops/checkout@v2"
with:
repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
# 2. Build Node.js project
- name: install
run: npm ci
image: node:18
# 3. Run build
- name: build
run: npm run build
image: node:18Below is an example of a typical successful pipeline flow.
Below is an example of a flow when checkout fails. The failed job is shown in red, and subsequent jobs are skipped.
Workflow Syntax Overview
The full structure of a Workflow YAML file. Detailed syntax for each field is covered in the sub-documents.
name: <string> # Workflow name (required)
triggers: <object> # Execution conditions (required)
env: <object> # Global environment variables (optional)
jobs: # Job definitions (required, at least 1)
<job_id>:
include: <string> # Workspace template reference (optional)
needs: <list> # Dependent Jobs (optional)
if: <expression> # Conditional execution (optional)
phase: <string> # Metadata (optional)
env: <object> # Job environment variables (optional)
services: <list> # Auxiliary services (optional)
steps: # Step list (can be omitted with include)
- name: <string>
run: <string> # Shell command
image: <string> # Container image
uses: <string> # Template reference
with: <object> # Template inputs
env: <object> # Step environment variables
id: <string> # Identifier for output referencesTop-level Schema
| Field | Required | Type | Description |
|---|---|---|---|
name | YES | string | Workflow name (max 255 characters, case-insensitive) |
triggers | YES | object | Execution conditions — see Triggers documentation |
jobs | YES | object | Job definitions (at least 1) — see Jobs documentation |
env | NO | object | Global environment variables — see Environment Variables documentation |
matrix | ❌ | - | Not supported (planned for future release) |