Workflow

Description

The workflow is the main entity in CDS. It allows you to chain jobs, using conditional branching.

As Code directory

A workflow is described directly on your repository inside the directory .cds/workflows/.

Permission

The permission manage-workflow on your project is mandatory to manage a workflow.

Fields

name: cds
repository:
  vcs: github
  name: ovh/cds
commit-status:
  ...
on: [push] 
integrations: [my-artifactory]
stages:
  ...
jobs:
  ...
env:   
  VAR_1: value
  VAR_2: value2
gates:
  ...

* mandatory fields

Repository

The repository linked to you workflow allows you to:

Commit-status:

A commit build status is always sent by CDS with default values. You can customize the title and description of the build status with the commit-status attribute.

commit-status:
  title: foo
  description: bar

On

Available hooks:

model-update and workflow-update are only available is the workflow definition is different from the repository field of your workflow. The hook will be triggered when default branch is updated, and will trigger the default branch of the destination repository

the on field has 2 formats

Array of string:

on: [push,pull-request,model-update,workflow-update]

Map

on:
  push:
    branches: [main,develop]
    paths: [^src/.*/.*.java$]
  model-update:
    models: [MYPROJ/github/ovh/resources/mymodel]
    target_branch: main
  pull-request:
    comment: "a comment here"
    types: ["opened","reopened","closed","edited"]
    branches: [main,develop]
    paths: [^src/.*/.*.java$]
  pull-request-comment:
    comment: "a comment here"
    types: ["created","deleted","edited"]
    branches: [main,develop]
    paths: [^src/.*/.*.java$]
  workflow-update:
    target_branch: main

Integrations

Allow a job to use an project integration.

Integration can be put directly on a job or at the workflow top level to be applied on all jobs

Supported integrations:

jobs

Jobs field is a map that contains all the jobs of your workflow. The key of the map is the name that will be display in CDS UI

jobs:
  myJob:
    runs-on: ./cds/worker-models/my-custom-ubuntu.yml
    vars: [varset1, varset2]
    integrations: [my-artifactory]
    steps:
     run: echo 'Hello World'
  mySecondJob:
    runs-on: ./cds/worker-models/my-custom-ubuntu.yml
    needs: [myJob]
    steps:
     run: echo 'Bye'

Step

A step represent

jobs:
  myjob:
    steps:
      - id: stepIdentifier
        run: echo 'Hello World' # cannot be used with `uses`
        uses: actions/checkout # cannot be used with `run`
        with:
          ref: develop
          sha: aefd1235
        if: failure()
        continue-on-error: true
        env:
          NEW_VAR: myValue

Inputs

Inputs allow you to define a list of variable that will be used in your job. If you use it all others contexts will be unavailable. This allows you to exactly control the inputs of your job

jobs:
  myjob:
    inputs:
      inp1: ${{ git.ref }}
      inp2: ${{ cds.workflow }}
      inp3: My Value

Strategy

Allow you to define a execution strategy for your job.

Available strategy:

jobs:
  myjob:
    strategy:
      matrix:
        version: ["go1.21", go1.22]
        os: [ubuntu, debian]
    steps:
      run: echo ${{ matrix.version }} - ${{ matrix.os }}

The matrix strategy allows you to template a job with matrix variables that will automatically create multiple jobs during the execution

In this example, CDS will create 4 jobs during execution with the given matrix context:

Services

Service are docker containers spawned with your job in a private network. For example it allows you to start a postreSQL DB for your tests

jobs:
  init:
    runs-on: .cds/worker-models/buildpack-deps-buster.yml
    services:
      myngnix:
        image: nginx:1.13
        env:
          NGINX_PORT: 80
        readiness:
          command: curl --fail http://myngnix:80
          interval: 10s
          timeout: 5s
          retries: 5 
      mypostgres:
        ...

Gates

Gates are hooks that allow you to manually trigger a job under certain conditions

gates:
  first-gate:
    if: ${{ git.ref == 'main' && gate.approve }}
    inputs:
      approve:
        type: boolean
    reviewers:
      groups: [release-team]
jobs:
  myGateJob:
    gate: first-gate

Stages

The use of stages allows you to structure and organize jobs in a modular way

stages:
  my-stage: 
  my-stage2:
    needs: [my-stage]

Conditions

Condition can be use at different level but share the same syntaxe

You can use all contexts to create your condition

Syntax

if: ${{ git.ref == "master" && cds.job == "MyJob" }}
or 
if: git.ref == "master" && cds.job == "MyJob"

Operators list