Skip to content

Manifest

Jump to bottom
fire-dragon edited this page May 13, 2021 · 6 revisions

Quick Start

Draft of workflow template can be created using the following command:

CodeReview.Orchestrator.exe new -o manifest.yaml

Output of this command may look as follows:

imports:
  folderPath: ./imports
sources:
  folderPath: ./src
artifacts:
  folderPath: ./artifacts
  exportOnCompletion: true
variables:
  MY_VAR_1: Value1
  MY_VAR_2: Value2
activities:
  git:
    image: dragon/jetbrains
    environment:
      MY_VAR_1: Value1
      MY_VAR_2: Value2
    volumes:
      useWindowsDefaults: false
      sources: /src
      artifacts: /artifacts
      imports: /imports
    settings:
      waitTimeoutSeconds: 3000
    requirements:
      os: Linux
      features:
      - feature1
    command:
    - mkdir
    - /mydir

Manifest Description

Typical manifest may look as follows:

imports:
  folderPath: ./imports
sources:
  folderPath: ./src
artifacts:
  exportOnCompletion: true
variables: 
  srcPath: /src
activities:
  git:
    image: godeltech/codereview.tools.gitprovider
    environment:
      GIT_REPOSITORY_URL: https://github.com/GodelTech/CodeReview.Orchestrator.git
      GIT_BRANCH: main
    volumes:
      sources: ${var.srcPath}
  roslyn:
    image: godeltech/codereview.analyzers.roslyn
    environment:
      SOLUTION_FILE_PATH: /src/CodeReview.Orchestrator.sln
    volumes:
      sources: ${var.srcPath}
  roslyn-converter:
    image: godeltech/codereview.file-converter
    command:
    - roslyn
    - --output
    - /artifacts/rolsyn-result.zip
    - --folder
    - /artifacts
    - --src
    - ${var.srcPath}/
    - --mask
    - '*.roslyn.json'

Manifest Properties

Imports Section

imports section defines settings used to initialize imports volume. List of properties can be found in the following table:

Property Mandatory Default Value Description
folderPath false ./imports Specifies location of folder to import into imports container. If relative path is specified manifest location is used as current directory. If folder specified in this property doesn't exist no import is performed.

Sources Section

sources section defines settings used to initialize sources volume. List of properties can be found in the following table:

Property Mandatory Default Value Description
folderPath false ./src Specifies location of folder to import into src container. If relative path is specified manifest location is used as current directory. If folder specified in this property doesn't exist no import of source code is performed.

Artifacts Section

artifacts section defines settings used to initialize artifacts volume. List of properties can be found in the following table:

Property Mandatory Default Value Description
folderPath false ./artifacts Specifies location of folder to export content of artifacts volume data.
exportOnCompletion false false Specifies if artifact volume needs to be exported or not after workflow execution is completed.

Variables Section

Variables section defines variables which can be used by other properties of manifest.

IMPORTANT: Variable values and expressions are evaluated once. This activity happens before workflow execution is started. Values can't be changed when workflow execution is in progress.

This section is dictionary. Here is how variable definitions may look like:

variables: 
  srcPath: /src
  var1: ${env:MY_ENV_VAR}
  var2: ${var:var1}
  var3: Literal and variable ${var:var1}
  var3: Literal and variable ${var:var1} and environment variable ${env:MY_ENV_VAR}

Variable value can be defined in the following ways:

  • Liteval value. This is value which doesn't refer to any variable.
  • Environment variable which is available to CodeReview.Orchestrator process. This reference has the following syntax: ${env:MY_ENV_VAR}. MY_ENV_VAR is name of environemnt variable to use. If value of enviroment variable is not defined empty string is used.
  • Reference to other variable. Reference has the following syntax: ${var:var1}. var is name of variable defined in variables section.
  • Variable be defined as mix of literal and references to variables or environment variables: Literal ${var:var1} and ${env:MY_ENV_VAR}

NOTE: Variable names are case-insensitive.

IMPORTANT: Maximal recursion depth for environment variable expression evaluation is 100. If recursion is deeper than specified value workflow execution is not started and execution is terminated with error.

Activities Section

This section defines sequence of activities executed one by one by CodeReview.Orchestrator. Activities are defined as YAML dictionary. Key of this dictionary is named of activity.

The following properties are available in activity definition:

Property Mandatory Description
image true Specifies Docker Image which needs to be used for container creation and execution .
environment false Specifies list of environment variables which need to be passed to Docker Container. Variable expressions can be used to define values. E.g. Literal ${var:var1} and ${env:MY_ENV_VAR} is valid value of environment variable.
command false List of command line parameters passed to Docker Container. Each element of list defines single parameter of command line.
requirements false Requirements which need to be satisfied by Docker Engine.
volumes false Volume mapping to Docker Container folders
settings false Docker Containe execution parameters.

Volumes

volumes section defines volume to folder mapping used for activity execution.

Property Mandatory Default Value Description
useWindowsDefaults false false Specifies if Windows paths must be used by default for folders used to mount values.
sources false /src (C:\src) Folder used to mount sources volume
imports false /imports (C:\imports) Folder used to mount imports volume
artifacts false /artifacts (C:\artifacts) Folder used to mount artifacts volume

Requirements

requirements section contains the following properties:

Property Mandatory Default Value Description
os false null Defines operation sysytem type required to execute Docker Container. When null value is specified default Docker Engine is used to executed activity.
features false List of features (tags) which need to be associated with Docker Engine executing activity.

Settings Section

settings section defines Docker-specific settings used to limit resources consumed by activity.

Property Mandatory Default Value Description
waitTimeoutSeconds false 900 Docker Container execution timeout If analysis exceeds specified timeout Docker Container is terminated. Long running analysis needs to specify proper value here.

Manifest Best Practices

The following guidelines may simplify creation and maintenance of CodeReview.Orchestrator manifests:

  • Avoid explicit declaration of parameters if values match defaults. This approach makes manifests shorter and easier to understand.
  • Consider usage of long parameter names. Many command line tools support long and short command line parameter names: -d and --destination. Long parameter names provide better understanding of their purpose and eliminate a need to study documentation of tool to understand parameter.
  • Use variables to avoid duplication of the same parameters in multiple places.
  • Use environent variables to pass security information rather than hardcode passwords and tokens in manifests.

Clone this wiki locally