Trigger events (on)

Under on, you can configure the trigger events that will start the CI/CD workflows in the repository.

Such events may include pushing changes to a remote repository branch or creating a pull request.

You can configure different workflows for different events. You can also configure triggers for specific branches or paths in the repository.

The following types of trigger events are supported:

If the trigger events are not specified, the push trigger event will be set for all workflows by default without any additional settings.

push

The push section executes workflows after pushing changes to a remote repository branch.

If the push section is present but its parameters are not specified, the push trigger event will be set for all workflows by default without any additional settings.

Simple push trigger event

A simple trigger event specifies only the name or list of names of workflows it will set off.

Example of a simple push trigger event with one workflow

on:
  push: my-workflow

Example of a simple push trigger event with a single workflow as a list

on:
  push:
    - my-workflow

Example of a simple push trigger event with multiple workflows

on:
  push: [my-workflow-1, my-workflow-2]

Example of a simple push trigger event with multiple workflows as a list

on:
  push:
    - [my-workflow-1, my-workflow-2]

Complex push trigger event

In addition to the name or list of names of workflows it will set off, a complex trigger event specifies additional settings to apply if triggered.

The following parameters are supported:

workflows
filter (optional)
skip_on_pull_request (optional)

workflows

The workflows field specifies the name (list of names) of workflow(s) the event will set off. If no workflows are specified, the complex trigger event is set for all workflows.

Example of a complex push trigger event with a single workflow

...
workflows: my-workflow
...

Example of a complex push trigger event with multiple workflows

...
workflows: [my-workflow-1, my-workflow-2]
...

filter

The filter field specifies the additional settings to apply when the complex trigger event is triggered.

Supported properties:

paths

The paths field specifies a filter or list of filters based on the modified files' paths.

If the paths field is not set, filtering by path is not used.

If the paths field is set as an empty list, the relevant complex trigger event will never be triggered.

You can specify filtering by path with a negation (!), in which case the relevant complex trigger event will be triggered if the paths of modified files are not subject to the filter.

Filters by path are specified in ascending priority order. In other words, after a filter with a negation, you can specify a filter without one that may cover, partially or fully, the effect of the filter with a negation.

If it is impossible for any reason to calculate paths of modified files, it will be considered that the changes are subject to the filter.

Example of a complex push trigger event with one filter by path

...
filter:
...
  paths: "pkg/**"
...

Example of a complex push trigger event with multiple filters by path

...
filter:
...
  paths: ["pkg/**", "internal/**"]
...

Example of a complex push trigger event with multiple filters by path, including with a negation

...
filter:
...
  paths: ["internal/**", "!internal/generated/**", "internal/generated/models/auth/**"]
...

The filter will apply to such files as internal/auth/auth.go and internal/generated/models/auth/auth.go. The filter will not apply to the internal/generated/models/data/data.go file.

branches

The branches field specifies a filter or list of filters based on branch names.

If the branches field is not set, filtering by branch name is not used.

If the branches field is set as an empty list, the relevant complex trigger event will never be triggered.

You can specify filtering by branch name with a negation (!), in which case the relevant complex trigger event will be triggered if the branch name is not subject to the filter.

Branch name filters are specified in ascending priority order. In other words, after a filter with a negation, you can specify a filter without one that may cover, fully or partially, the effect of the filter with a negation.

Example of a complex push trigger event with one filter by branch name

...
filter:
...
  branches: "feature/**"
...

Example of a complex push trigger event with multiple filters by branch name

...
filter:
...
  branches: ["feature/**", "bugfix/**"]
...

Example of a complex push trigger event with multiple filters by branch name, including with a negation

...
filter:
...
  branches: ["feature/**", "!feature/internal/**", "feature/internal/security/**"]
...

The filter will apply to such branches as feature/OO-7 and feature/internal/security/OO-777. The filter will not apply to the feature/internal/OO-77 branch.

skip_on_pull_request

The skip_on_pull_request field specifies whether to skip workflow executions if there are pull requests with the Open or Draft status based on the branch to which changes are pushed. It can either be true or false.

For example, the following configuration will ignore push trigger events for feature/** branches if there is an open pull request from those branches to other branches.

on:
  push:
    - workflows: o_yaml
      filter:
        branches: "feature/**"
      skip_on_pull_request: true

Note

As long as there are no open pull requests from the specified branches, the behavior will be completely similar to the on:push trigger event without the skip_on_pull_request: true parameter specified.

Since a pull request cannot be created without pushing changes to a branch, workflows will run as normal for all push events before a pull request is created.

Example of one complex push trigger event

on:
  push:
    workflows: ci-workflow
    filter:
      branches: "feature/**"
      paths: "ci/**"

Example of a combination of simple and complex push trigger events

on:
  push:
    - common-workflow-1
    - [common-workflow-2, common-workflow-3]
    - workflows: ci-workflow
      filter:
        branches: "feature/**"
        paths: "ci/**"

pull_request

The pull_request section executes workflows after creating a pull request.

Same as the push section, pull_request supports simple and complex trigger events.

For complex trigger events, the following parameters are supported:

workflows: Same as the push:workflows field.
filter:
- paths: Same as the push:filter:paths field.
- source_branches: Filtering based on branches the changes come from.
- target_branches: Filtering based on branches the changes will be added to.

Example of a pull_request trigger event without filters

on:
  pull_request: my-workflow

Example of a pull_request trigger event with all filters

on:
  pull_request:
    - workflows: [ci-workflow, ide-workflow]
      filter:
        source_branches: "feature/**"
        target_branches: ["master", "feature/**"]
        paths: "ci/**"