Execution Model

gitStream is triggered on new pull requests (PRs) for repositories that have gitStream installed. Upon triggering, gitStream collects context variables and evaluates the automation rules to determine which ones are relevant.

Organization-level rules and repository rules

When a central cm repository is set with the CI/CD runner, the events for PRs from all installed repositories shall be evaluated in the cm repository pipeline, considering the organization-level and PR repository rules.

Triggering Mechanism

gitStream automations are triggered by events related to pull requests (PRs). You can specify triggers to fine-tune which events should initiate automations.

Implicit triggers

By default, gitStream evaluates any new commit pushed to the PR, triggering automation evaluation.

Additionally, if any of the automation rules reference the following pr context variables: pr.comments, pr.title, pr.description, or pr.labels, gitStream shall trigger and will initiate automation rules evaluation where there are changes to the PR comments, title, description, or labels respectfully.

This allows for greater flexibility in the automation process, ensuring that the relevant automation rules are evaluated and triggered when necessary. The execution model ensures the automation process is streamlined, efficient, and effective.

Explicit triggers

gitstream supports an explicit triggering mechanism. When using explicit triggers, the automations will run only according to the defined triggers, which means the Implicit triggers will not work. Automations triggered by explicit triggers will also be invoked on draft PRs

Triggers can be defined globally at the file level or specifically for each automation. Triggers are applied only to the file(s) where they are declared.

triggers section

Use explicit triggers to enhance the control and customization of automations in gitStream, when you need to define precisely when and how automations should be triggered based on various events and actions within pull requests.

The triggers is section specifies when automations are executed, supporting include and exclude lists for branch and repository patterns at the file level.

The on keyword can also be used within individual automations to define specific events that trigger those automations. Add the on keyword under the triggers key in the file and/or to a specific automation to define explicit triggers.

gitStream supports the following explicit triggers:

Explicit triggers are set independently per each automation block and can be configured at the file level, specific to each automation separately or in combination. If triggers are listed at the file level and specific automation, the automation will be triggered according to both triggers. If an automation block does not have explicit triggers configured, it will be triggered according to the default (implicit) triggers.

Usage example:

triggers:
  on:
    - pr_created
    - commit
  exclude:
    branch:
      - hotfix

automations:
  skip_github_action_label:
    on:
      - label_added
    if:
      - {{ pr.labels | match(term='experimental') | some }}
    run:
      - action: add-github-check@v1
        args:
          check_name: production-ci
          conclusion: skipped

Note on Matching:

• When using a String as the matching type, the values in triggers.include.* and triggers.exclude.* require exact matches. This means that the names of branches or repositories must exactly match the specified string to either trigger or prevent triggering the automation.
• For more precise control, use a regular expression (regex) format: r/REGEX_PATTERN/.

Default Behavior:

• Implicit triggers are the default behavior if the automation doesn't have explicit triggers configured.
• The automation runs for all branches and repositories if neither include nor exclude is specified.

Exclude/Include prioritization

• Exclude overrides the include option. Thus, a repo will be excluded when a it matches both the include and exclude lists.

  In the following example, the automations in the file will be triggered for all repositories that contain the string feature, except for the repository my_feature

  triggers:
    include:
      repository:
        - r/feature/
    exclude:
      repository:
        - my_feature
  

Examples

• Assign code expert reviewer when the PR is created and after each commit. Ignore branches with the string "hotfix" in them

  triggers:
    on:
      - pr_created
      - commit
    exclude:
      branch:
        - hotfix
  
  automations:
    assign_code_experts:
      if:
        - true
      run:
        - action: add-reviewers@v1
          args:
            reviewers: {{ repo | codeExperts(gt=10) }}
  

• Explain code experts only if the label “suggest-reviewer” exists. The automation will be triggered after each commit and after each label addition. If the label “suggest-reviewer” exists, it will trigger the explain-code-experts automation

  triggers:
    on:
      - commit
  
  automations:
    explain_code_experts:
      on:
        - label_added
      if:
        - {{ pr.labels | match(term='suggest-reviewer') | some }}
      run:
        - action: explain-code-experts@v1
          args:
            gt: 10
  

• Trigger only specific automations branch pattern A, and trigger other automation for all other branches except those that fit the pattern REGEX_PATTERN

  # Automation in this file will trigger only for branch pattern REGEX_PATTERN
  triggers:
    include:
      branch:
        - r/REGEX_PATTERN/
  

  # Automations in this file will trigger for all branches except pattern REGEX_PATTERN
  triggers:
    exclude:
      branch:
        - r/REGEX_PATTERN/