Skip to content

Overview gitstream.cm

This document is a reference for the gitStream 1.x, used in .cm/gitstream.cm file. You can edit the .cm/gitstream.cm and add your own checks and automations. Check out the Automation examples

Context variables

gitStream includes a collection of variables called contexts. These variable has all the inputs you need to code your automation, including files names and paths, code that was changed or who did the change. See more here.

Filter functions

Filter funstions are essentially callable functions that can be applied to variables. They are called with a pipe operator | and can take arguments inside parentheses ( ). The logic expressions are based on Jinja2 syntax, supported by Nunjucks library.

See more about the Nunjucks built-in filters here, and about gitStream built-in filters here.

Automation actions

Specify the desired automations that are triggered when all conditions are met, read more here.

The conditions are evaluated on new Pull Requests or changes to the Pull Request.

PRs that are marked as Draft are ignored by default, you can change that, see config .

Schema

The following sections are used in .cm file to describe the desired automations:

manifest

The first section in a gitstream.cm file is the manifest.

manifest: 
  version: 1.0

The only field required is version.

Key Required Type Description
manifest Y Map The manifest section root
manifest.version Y String Specify the .cm spec version: 0.1, 1.0

The manifest version field is used to parse the .cm file, in the future if breaking changes are introduced to the parser then older automation will be still supported.

config

The config section is optional in gitstream.cm file and is used to specify configuration for the way gitStream works.

Key Required Type Default Description
config N Map - The config section root
config.ignore_files N [String] - Specifies files that will not be included in the context variables

config.ignore_files supports glob pattern matching that contains list of files to ignore, for example:

config:
  ignore_files:
    - 'yarn.lock'
    - 'package-lock.json'
    - 'openapi.json'
    - 'ui/src/**/*Model.d.ts'

automations

The automations section defines the automations and their conditions.

automations:
  mark_small_pr:
    if:
      - {{ checks.size.is.xsmall }}
    run:
      - action: add-label@v1
        args:
          label: xsmall

Each automation includes its name, and few fields: if and run.

Key Required Type Description
automations Y Map The automations section root
automations.NAME Y Map User defined name of the automation, can be any string
automations.NAME.if Y Map List of conditions
automations.NAME.run Y Map The automation to run if all conditions are met

The if field includes the list of conditions. The conditions are checked when a pull request is opened or changed, if all the conditions pass, the automation is executed.

The run field includes the automation to execute. It includes the following fields:

Key Required Type Description
action Y String The action pointer
engine N String The action engine, default is gitstream
args N List The action inputs list

For gitstream engine, the action is specified by: name@version

gitStream supported actions, see actions.

Reusing checks

You can define an accessory section, e.g. checks, that defines common conditions, and resue.

size:
  is:
    small: {{ branch.diff.size < 20 }}
    medium: {{ branch.diff.size >= 20 and branch.diff.size < 100 }}
    large: {{ branch.diff.size >= 100 }}
automations:
  approve_small:
    if:
      - {{ size.is.small }}
    run:
      - action: approve@v1
  mark_small_medium:
    if:
      - {{ size.is.small or size.is.medium }}
    run:
      - action: add-label@v1
        args:
          label: 'good-size'