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.

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.

  • close to close the Merge Request.
  • reopen to reopen the Merge Request.
  • lock_discussion to prevent further discussions on the Merge Request.
  • unlock_discussion to allow discussions on the Merge Request.
  • approve to approve the Merge Request.
  • unapprove to approve 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

  • 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

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).