From 8083849c7be9f0f096a4fb30f026d7864d68973e Mon Sep 17 00:00:00 2001 From: ofer affias Date: Mon, 13 May 2024 14:01:17 +0300 Subject: [PATCH] add the triggers section to the cm file syntax page, reorder the triggres docs ang provide an example with entire CM context --- docs/cm-file.md | 17 +++++- docs/execution-model.md | 113 ++++++++++++++++++++++++---------------- 2 files changed, 85 insertions(+), 45 deletions(-) diff --git a/docs/cm-file.md b/docs/cm-file.md index 755e7825..ab6c475f 100644 --- a/docs/cm-file.md +++ b/docs/cm-file.md @@ -71,7 +71,7 @@ For each PR the following automation rules are applied: When organization level rules are defined, then the CI/CD will be executed on the `cm` repository on behalf of the PR repository. -### Setting up Global Automation rules +### Setting up Global Automation rules By utilizing the following techniques, you can effectively combine and manage global and repository rules to customize the behavior of your automations to fit the specific requirements of your repositories: @@ -182,6 +182,21 @@ On the other hand, when using `explainRankByGitBlame` with `add-comment@v1` it s 1. `rankByGitBlame` will drop `null` users 2. `explainRankByGitBlame` will NOT drop `null` users +#### `triggers` + +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. + +```yaml+jinja +triggers: + on: + - pr_created + - commit + exclude: + branch: + - hotfix +``` + +Read more here: [triggers](/execution-model#explicit-triggers). #### `automations` diff --git a/docs/execution-model.md b/docs/execution-model.md index b7f5418c..ddc01486 100644 --- a/docs/execution-model.md +++ b/docs/execution-model.md @@ -9,12 +9,28 @@ When a central `cm` repository is set with the CI/CD runner, the events for PRs ## 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. -### Trigger Configuration + +### 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.md#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 :fontawesome-brands-github: + +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` -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. +#### `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. | Key | Type | Description | | ----------------------------------------------------- | ----------------- | -------------------------------------------------------------- | @@ -24,6 +40,50 @@ Specifies when automations are executed, supporting `include` and `exclude` list | `triggers.include.repository` | [String or regex] | Repositories that match will trigger the automation. | | `triggers.exclude.repository` | [String or regex] | Repositories that match will not trigger the automation. | +gitStream supports the following explicit triggers: + +| Triggering event | Explicit Trigger :fontawesome-brands-github: | Default (implicit triggers) | +| --------------------------------------------------------------------- | -------------------------------------------- | ------------------------------ | +| Creating a PR | `pr_created` | `on` | +| Commit | `commit` | `on` | +| Adding label | `label_added` | when `pr.label` in `.cm` | +| Removing label | `label_removed` | when `pr.label` in `.cm` | +| :fontawesome-brands-github: Merging the PR | `merge` | `off` | +| Adding new comment | `comment_added` | when `pr.comment` in `.cm` | +| :fontawesome-brands-github: Editing an existing comment | - | when `pr.comment` in `.cm` | +| Title change | - | when `pr.title` in `.cm` | +| Description change | - | when `pr.description` in `.cm` | +| :fontawesome-brands-github: Transition from draft to ready for review | `pr_ready_for_review` | `off` | +| :fontawesome-brands-github: transition from any state to closed | `pr_closed` | `off` | +| :fontawesome-brands-github: transition from closed to open | `pr_reopened` | `off` | + +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: + +```yaml+jinja +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. @@ -37,9 +97,9 @@ Specifies when automations are executed, supporting `include` and `exclude` list **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` - ``` + ```yaml+jinja triggers: include: repository: @@ -49,42 +109,6 @@ Specifies when automations are executed, supporting `include` and `exclude` list - my_feature ``` - -### 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.md#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 :fontawesome-brands-github: -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 - -#### Explicit triggers syntax -Use explicit triggers to enhance the control and customization of automations in gitStream, allowing users to define precisely when and how automations should be triggered based on various events and actions within pull requests. - -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: - -| Triggering event | Explicit Trigger :fontawesome-brands-github: | Default (implicit triggers) | -| --------------------------------------------------------------------- | -------------------------------------------- | ------------------------------ | -| Creating a PR | `pr_created` | `on` | -| Commit | `commit` | `on` | -| Adding label | `label_added` | when `pr.label` in `.cm` | -| Removing label | `label_removed` | when `pr.label` in `.cm` | -| :fontawesome-brands-github: Merging the PR | `merge` | `off` | -| Adding new comment | `comment_added` | when `pr.comment` in `.cm` | -| :fontawesome-brands-github: Editing an existing comment | - | when `pr.comment` in `.cm` | -| Title change | - | when `pr.title` in `.cm` | -| Description change | - | when `pr.description` in `.cm` | -| :fontawesome-brands-github: Transition from draft to ready for review | `pr_ready_for_review` | `off` | -| :fontawesome-brands-github: transition from any state to closed | `pr_closed` | `off` | -| :fontawesome-brands-github: transition from closed to open | `pr_reopened` | `off` | - -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. - ### Examples - Assign code expert reviewer when the PR is created and after each commit. Ignore branches with the string "hotfix" in them @@ -109,7 +133,8 @@ automations: - 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 -``` yaml+jinja + + ```yaml+jinja triggers: on: - commit @@ -128,7 +153,7 @@ automations: - Trigger only specific automations branch pattern A, and trigger other automation for all other branches except those that fit the pattern REGEX_PATTERN - ``` + ```yaml+jinja # Automation in this file will trigger only for branch pattern REGEX_PATTERN triggers: include: @@ -136,7 +161,7 @@ automations: - r/REGEX_PATTERN/ ``` - ``` + ```yaml+jinja # Automations in this file will trigger for all branches except pattern REGEX_PATTERN triggers: exclude: