Skip to content

Manifest

Jump to bottom
pNovikau edited this page Feb 9, 2022 · 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:

volumes:
  imports:
    readOnly: false
    targetFolder: /imports
    folderToImport: ./imports
  sources:
    readOnly: true
    targetFolder: /src
    folderToImport: ./src
  artifacts:
    readOnly: false
    targetFolder: /artifacts
    folderToOutput: ./artifacts
variables:
  MY_VAR_1: Value1
  MY_VAR_2: Value2
activities:
  git:
    image: dragon/jetbrains
    environment:
      MY_VAR_1: Value1
      MY_VAR_2: Value2
    volumes:
      sources:
        readOnly: true
        targetFolder: /sources
    settings:
      waitTimeoutSeconds: 3000
    requirements:
      os: Linux
      features:
      - feature1
    command:
    - mkdir
    - /mydir
  resharper:
    image: dragon/jetbrains
    environment:
      MY_VAR_1: Value1
      MY_VAR_2: Value2
    volumes:
      sources:
        readOnly: true
        targetFolder: C:\src
      imports:
        readOnly: true
        targetFolder: C:\imports
      artifacts:
        readOnly: true
        targetFolder: C:\artifacts
    settings:
      waitTimeoutSeconds: 3000
    requirements:
      os: Windows
      features:
      - feature2
      - feature3
    command:
    - mkdir
    - /mydir
  roslyn:
    image: dragon/roslyn
    environment:
      MY_VAR_1: Value1
      MY_VAR_2: Value2
    volumes: {}
    settings:
      waitTimeoutSeconds: 3000
    command:
    - mkdir
    - /mydir

Manifest Description

Typical manifest may look as follows:

imports:
    readOnly: false
    targetFolder: /imports
    folderToImport: ./imports
sources:
  readOnly: true
  targetFolder: /src
  folderToImport: ./src
artifacts:
  readOnly: false
  targetFolder: /artifacts
  folderToOutput: ./artifacts
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:
        targetFolder: ${var.srcPath}
  roslyn:
    image: godeltech/codereview.analyzers.roslyn
    environment:
      SOLUTION_FILE_PATH: /src/CodeReview.Orchestrator.sln
    volumes:
      sources:
        targetFolder: ${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

Volumes Section

volumes section defines shared volumes across activities. Volume can be overridden for specific activity. Example if need to specify the different targetFolder for a activity, volume can be overridden as follow:

sources:
  readOnly: true
  targetFolder: /src
  folderToImport: ./src
activities:
  git:
    image: godeltech/codereview.tools.gitprovider
    environment:
      GIT_REPOSITORY_URL: https://github.com/GodelTech/CodeReview.Orchestrator.git
      GIT_BRANCH: main
    volumes:
      sources:
        targetFolder: /source
Property Mandatory Default Value Description
readOnly false true Specifies is a volume will be created as a read-only
targetFolder true NONE Specifies the location of the folder in the container
folderToOutput false Null Specifies the location of the folder to export content of volume data. If Null the export action will be skipped
folderToImport false Null Specifies location of folder to import into container volume. If Null the import action will be skipped

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 Volumes mapping to Docker Container folders
settings false Docker Containe execution parameters.

Volumes

volumes section defines volumes for the activity. Can specify an override for shared volumes, and can also specify a new volume for the current action.

Property Mandatory Default Value Description
readOnly false true Specifies is a volume will be created as a read-only
targetFolder true NONE Specifies the location of the folder in the container
folderToOutput false Null Specifies the location of the folder to export content of volume data. If Null the export action will be skipped
folderToImport false Null Specifies location of folder to import into container volume. If Null the import action will be skipped

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