Skip to content

Configuration file

The default configuration filename is .scm-engine.yml, either in current working directory, or if you are in a Git repository, the root of the project.

The file path can be changed via --config CLI flag and $SCM_ENGINE_CONFIG_FILE environment variable.

ignore_activity_from

What is 'activity'?

SCM-Engine defines activity as comments, reviews, commits, adding/removing labels and similar actions made on a change request.

Generally, activity is what you see in the Merge/Pull Request timeline in the browser UI.

Configure what users that should be ignored when considering activity on a Merge Request

ignore_activity_from.bots

Should bot users be ignored when considering activity? Default: false

ignore_activity_from.usernames[]

A list of usernames that should be ignored when considering user activity. Default: []

ignore_activity_from.emails[]

A list of emails that should be ignored when considering user activity. Default: []

NOTE: If a user do not have a public email configured on their profile, that users activity will never match this rule.

include[]

What are includes?

scm-engine has support for importing some (or all) of its configuration from other repositories.

The scm-engine API token MUST be able to read the content of the referenced projects via the API

Limitations and restrictions of remote included configuration files

This is immensely useful if you want to share configuration between many projects, like a centralized scm-engine-library project with common patterns and configuration files.

  • Only actions and label configurations keys are supported in included configuration files.
  • Nested/Recursive includes are NOT support.
  • Merging/overriding configurations are NOT supported; included configuration will always append to the existing configuration.
  • All included files MUST exist and be valid; any missing file or invalid configuration will result in failure.
  • scm-engine will read all files from a project in a single request where possible; up to 100 files are supported.
  • scm-engine do NOT cache any remote configuration files; they are always read during evaluation cycle.

Example 'include' configuration loading 4 files from the 'platform/scm-engine-library' project

include:
  - project: platform/scm-engine-library
    files:
      - label/change-type.yml
      - label/last-commit-age.yml
      - label/need-rebase.yml
      - life-cycle/close-merge-request-3-weeks.yml

  label:
    - ....

  actions:
    - ...

include[].project

The GitLab repository slug to read configuration files, like example/project.

include[].files

The list of files to include from the project. The paths must be relative to the repository root, e.x. label/some-config-file.yml; NOT /label/some-config-file.yml

include[].ref

Optional Git reference to read the configuration from; it can be a tag, branch, or commit SHA.

If omitted, HEAD is used; meaning your default branch.

actions[]

What are actions?

Actions can modify a Merge Request in various ways, for example, adding a comment or closing the Merge Request.

Due to actions powerful and flexible capabilities, they can be a bit harder to get right than adding and removing labels.

Please see the examples page for use-cases.

The actions key is a list of actions that can be taken on a Merge Request.

actions[].name

The name of the action, this is purely for debugging and your convenience.

It's encouraged to be descriptive of the actions.

actions[].if

This field must be a valid Expr lang script

Please see the following pages for more information:

The script must return a boolean

A key controlling if the action should executed or not.

actions[].if.then[]

The list of operations to take if the action.if returned true.

actions[].if.then[].action

This key controls what kind of action that should be taken.

  • approve to approve the Merge Request.
  • unapprove to approve the Merge Request.
  • close to close the Merge Request.
  • reopen to reopen the Merge Request.

  • comment to add a comment to the Merge Request

    Additional fields:

    • (required) message The message that will be commented on the Merge Request.
    'comment' example
    - action: comment
  message: |
    Hello world

  • lock_discussion to prevent further discussions on the Merge Request.

  • unlock_discussion to allow discussions on the Merge Request.

  • add_label to add an existing label to the Merge Request

    Additional fields:

    • (required) label The label name to add.
    add_label example
    - action: add_label
  label: example

  • remove_label to remove a label from the Merge Request

    Additional fields:

    • (required) label The label name to add.
    remove_label example
    - action: remove_label
  label: example

  • update_description updates the Merge Request Description

    Additional fields:

    • (required) replace A list of key/value pairs to replace in the description. The key is the raw string to replace in the Merge Request description. The value is an Expr Lang expression returning a string that key will be replaced with - all Script Attributes and Script Functions are available within the script.
    update_description example
    - action: update_description
  replace:
    "${{CI_MERGE_REQUEST_IID}}": "merge_request.iid"

label[]

What are labels?

Labels are a way to categorize and filter issues, merge requests, and epics in GitLab. -- GitLab documentation

The label key is a list of the labels you want to manage.

These keys are shared between the conditional and generate label strategy. (more above these below!)

label[].strategy

SCM Engine supports two strategies for managing labels, each changes the behavior of the script.

  • conditional (default, if strategy key is omitted), where you provide the name of the label, and a script that returns a boolean for wether the label should be added to the Merge Request.

    The script must return a boolean value, where true mean add the label and false mean remove the label.

  • generate, where your script generates the list of labels that should be added to the Merge Request.

    The script must return a list of strings, where each label returned will be added to the Merge Request.

label[].strategy = conditional

Use the conditional strategy when you want to add/remove a label on a Merge Request depending on something. It's the default strategy, and the most simple one to use.

Please see the Add label if a file extension is modified example for how to use this

label[].strategy = generate

Use the generate strategy if you want to create dynamic labels, for example, depending labels based on the file structure within your project.

Thanks to the dynamic nature of the generate strategy, it has fantastic flexibility, at the cost of greater complexity.

Please see the generate labels from directory layout example for how to use this

label[].name

  • When using label.strategy: conditional

    REQUIRED The name of the label to create.

  • When using label.strategy: generate

    OMITTED The name field must not be set when using the generate strategy.

label[].script

This field must be a valid Expr lang script

Please see the following pages for more information:

Depending on the label.strategy: used, the behavior of the script changes, read more about this below.

label[].color

Note

When used on strategy: generate labels, all generated labels will have the same color.

color is a mandatory field, controlling the background color of the label when viewed in the User Interface.

You can either provide your own hex value (e.g, #FFFF00) or use the Twitter Bootstrap color variables, for example$blue-500 and $teal.

label[].description

When used on strategy: generate labels, all generated labels will have the same description.

An optional key that sets the description field for the label within GitLab.

Descriptions are shown in the User Interface when you hover any label.

label[].priority

When used on strategy: generate labels, all generated labels will have the same priority.

An optional key that controls the GitLab Label Priority.

label[].skip_if

This field must be a valid Expr lang script

Please see the following pages for more information:

The script must return a boolean value

An optional key controlling if the label should be skipped (meaning no removal or adding of labels).