Skip to content

Commit

Permalink
Merge pull request #512 from linear-b/enhance-triggers-section
Browse files Browse the repository at this point in the history 
Triggers docs improvements
  • Loading branch information
@vim-zz
vim-zz committed May 13, 2024
2 parents b367f50 + 8083849 commit 158f118
Show file tree
Hide file tree
Showing 2 changed files with 85 additions and 45 deletions.
17 changes: 16 additions & 1 deletion docs/cm-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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`

Expand Down
113 changes: 69 additions & 44 deletions docs/execution-model.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| ----------------------------------------------------- | ----------------- | -------------------------------------------------------------- |
Expand All @@ -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.
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand All @@ -128,15 +153,15 @@ 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:
branch:
- r/REGEX_PATTERN/
```

```
```yaml+jinja
# Automations in this file will trigger for all branches except pattern REGEX_PATTERN
triggers:
exclude:
Expand Down

0 comments on commit 158f118

Please sign in to comment.