---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/on.md
  - href: en/sourcecraft/ci-cd-ref/on.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt

# Trigger events (on)

<!-- source: en/_includes/sourcecraft/ci-cd/on-description.md -->
Under `on`, you can configure the _trigger events_ that will start the CI/CD [workflows](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#workflows) in the repository. Such events may include pushing changes to a remote repository branch (`push`), creating a pull request (`pull_request`), or a scheduled execution (`schedule`).

{% note warning %}

For the trigger event to fire, the `.sourcecraft/ci.yaml` file must be in the repository's main branch, e.g., `main` or `master`. You can set the main branch in the [repository settings](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/repo-edit.md).

{% endnote %}

You can configure different workflows for different events. You can also configure triggers for specific branches or paths in the repository.
<!-- endsource: en/_includes/sourcecraft/ci-cd/on-description.md -->

The following types of trigger events are supported:
* [push](#push): Pushing changes to a remote repository branch.
* [pull_request](#pull-request): Creating a [pull request](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#pr).
* [schedule](#schedule): Scheduled execution.

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

## push {#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.

A _simple `push`_ trigger event only specifies the name or list of names of the workflows it will set off.

##### Example of a simple push trigger event with one workflow {#simple-push-one-process}

```yaml
on:
  push: my-workflow
```

##### Example of a simple push trigger event with a single workflow as a list {#simple-push-one-process-list}

```yaml
on:
  push:
    - my-workflow
```

##### Example of a simple push trigger event with multiple workflows {#simple-push-many-processes}

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

##### Example of a simple push trigger event with multiple workflows as a list {#simple-push-many-processes-list}

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

Beyond the name or list of names of the workflows it will set off, a _complex `push`_ trigger event specifies additional settings to apply if triggered.

Supported properties:
* [workflows](#complex-push-workflows)
* [filter](#complex-push-filter) (optional)
* [skip_on_pull_request](#complex-push-skip) (optional)

### workflows {#complex-push-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 {#complex-push-one-process}

```yaml
...
workflows: my-workflow
...
```

##### Example of a complex push trigger event with multiple workflows {#complex-push-many-processes}

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

### filter {#complex-push-filter}

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

Supported properties:
* [paths](#complex-push-paths): Filter or list of filters based on the modified files' paths.
* [branches](#complex-push-branches): Filter or list of filters based on branch names.
* [tags](#complex-push-tags): Filter or list of filters based on tag names.

<!-- source: en/_includes/sourcecraft/ci-cd/filter-tag-with-others.md -->
{% note warning %}

You cannot use the `tags` filter together with `branches`, `paths`, or their combination in the `filter` section. Using the `tags` parameter with `branches` and `paths` is a syntax error.

To configure workflow execution by both branch names and paths as well as tag names, describe two separate events in the configuration: one with the `branches` and `paths` filters, and the other one, with the `tags` filter. For examples, see [Example of a complex push trigger event with filters by tag, path, and branch](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md#complex-push-tags-branches-paths).

{% endnote %}
<!-- endsource: en/_includes/sourcecraft/ci-cd/filter-tag-with-others.md -->

#### paths {#complex-push-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.

{% note tip %}

Only use a negation filter together with other filters by path. The negation filter itself only prohibits running the trigger event. For more information, see [this example](#complex-push-many-paths-with-not).

{% endnote %}

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.

For more on syntax and rules for filters, see [Filters and patterns in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/filters-by-paths.md).

##### Example of a complex push trigger event with one filter by path {#complex-push-one-path}

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

##### Example of a complex push trigger event with multiple filters by path {#complex-push-many-paths}

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

##### Example of a complex push trigger event with multiple filters by path, including with a negation {#complex-push-many-paths-with-not}

```yaml
...
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.

You can configure a workflow to be executed for all files in a repository except those you specify, e.g.:

```yaml
...
filter:
...
  paths: ["**", "!internal/generated/**"]
...
```

#### branches {#complex-push-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. 

{% note tip %}

Only use a negation filter together with other filters by branch. The negation filter itself only prohibits running the trigger event. For more information, see [this example](#complex-push-many-branches-with-not).

{% endnote %}

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.

For more on syntax and rules for filters, see [Filters and patterns in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/filters-by-paths.md).

##### Example of a complex push trigger event with one filter by branch name {#complex-push-one-branch}

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

##### Example of a complex push trigger event with multiple filters by branch name {#complex-push-many-branches}

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

##### Example of a complex push trigger event with multiple filters by branch name, including with a negation {#complex-push-many-branches-with-not}

```yaml
...
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.

You can configure a workflow to be executed for all branches in a repository except those you specify, e.g.:

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

#### tags {#complex-push-tags}

The `tags` field specifies a filter or list of filters based on tag names.

If the `tags` field is not set, filtering by tag does not apply. 

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

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

{% note tip %}

Only use a negation filter with together with other filters by tag. The negation filter itself only prohibits running the trigger event. For more information, see [this example](#complex-push-many-tags-with-not).

{% endnote %}

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

<!-- source: en/_includes/sourcecraft/ci-cd/filter-tag-with-others.md -->
{% note warning %}

You cannot use the `tags` filter together with `branches`, `paths`, or their combination in the `filter` section. Using the `tags` parameter with `branches` and `paths` is a syntax error.

To configure workflow execution by both branch names and paths as well as tag names, describe two separate events in the configuration: one with the `branches` and `paths` filters, and the other one, with the `tags` filter. For examples, see [Example of a complex push trigger event with filters by tag, path, and branch](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md#complex-push-tags-branches-paths).

{% endnote %}
<!-- endsource: en/_includes/sourcecraft/ci-cd/filter-tag-with-others.md -->

For more on syntax and rules for filters, see [Filters and patterns in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/filters-by-paths.md).

##### Example of a complex push trigger event with one filter by tag name {#complex-push-one-tag}

```yaml
...
filter:
...
  tags: "version-*"
...
```

##### Example of a complex push trigger event with multiple filters by tag name, including with a negation {#complex-push-many-tags-with-not}

```yaml
...
filter:
...
  tags: ["version-*", "!version-alpha-*"]
...
```

In this case, the workflow will be executed for all tags whose names begin with `version-` except those beginning with `version-alpha-`.

You can configure a workflow to be executed for all tags in a repository except those you specify, e.g.:

```yaml
...
filter:
...
  tags: ["**", "!version-alpha-*"]
...
```

##### Example of a complex push trigger event with filters by tag, path, and branch {#complex-push-tags-branches-paths}

To run `ci-workflow` both upon modifying the `ci/**` directory content in the `main` branch and upon pushing the `ci-version-*` tag, create two separate trigger events:

```yaml
on:
  push:
    - workflows: ci-workflow
      filter:
        branches: "main"
        paths: "ci/**"
    - workflows: ci-workflow
      filter:
        tags: "ci-version-*"
```

### skip_on_pull_request {#complex-push-skip}

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

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

{% note info %}

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 be executed per usual for all `push` events before a pull request is created.

{% endnote %}

##### Example of one complex push trigger event {#complex-push-examples}

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

##### Example of a combination of simple and complex push trigger events {#simple-complex-push-examples}

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

## pull_request {#pull-request}

The `pull_request` section executes workflows after creating a pull request.

Same as the [push](#push) section, `pull_request` supports [simple](#simple-push) and [complex](#complex-push) 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 {#pull-request-without-filters}

```yaml
on:
  pull_request: my-workflow
```

##### Example of a pull_request trigger event with all filters {#pull-request-with-all-filters}

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

## schedule {#schedule}

The `schedule` section executes scheduled workflows in the main branch of the repository, e.g., `main` or `master`. Supported properties:
* `workflows`: Same as the `push:workflows` field.
* `interval`: Execution interval in hours or minutes, e.g., `1h` or `7m`. The minimum value is `1m`. Cannot be used together with `cron`.
* `cron`: [Cron expression](https://en.wikipedia.org/wiki/Cron), e.g., `"25 * * * *"`, which means on the 25th minute of each hour. Cannot be used together with `interval`.
* `description`: Random description (optional).

{% note warning %}

A scheduled workflow is executed on behalf of the user who last edits the `schedule` section in the `.sourcecraft/ci.yaml` file in the main branch. The rule covers the edits of all the schedule fields other than `description`.

However, if a new element is added to the `schedule` section on behalf of one user, while the old ones created by another user remain unchanged, then the workflows under different schedules will be executed on behalf of different users.

{% endnote %}

Scheduled workflow executions support [inputs](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md#inputs). For more information, see [Example of schedule trigger events with inputs](#inputs-schedule).

##### Example of schedule trigger events {#schedule-example}

```yaml
on:
  schedule:
    - workflows: first-workflow
      interval: 30m
      description: interval schedule

    - workflows: 
        - first-workflow
        - second-workflow
      cron: "25 * * * *"
      description: cron schedule
```

Based on this configuration, the following workflows will be automatically executed in the main branch of the repository:
* `first-workflow`, every 30 minutes.
* `first-workflow` and `second-workflow`, on the 25th minute of each hour.

##### Example of schedule trigger events with inputs {#inputs-schedule}

```yaml
on:
  # Scheduled workflow execution
  schedule:
    - interval: 1h
      workflows:
        # Executing the workflow with one set of inputs
        echo-inputs-workflow:
          inputs:
            first: "Hello"
            second: "Bye"
    - interval: 30m
      workflows:
        # Executing the same workflow, but with different inputs
        echo-inputs-workflow:
          inputs:
            - name : first
              value : "Hi"
            - name : second
              value : "Bye"
        # Executing the workflow without inputs
        workflow-without-inputs: {}

workflows:
  echo-inputs-workflow:
    inputs:
      # Declaring inputs
      first:
        type: string
        description: First input value
      second:
        type: string
        description: Second input value
    tasks:
      - sample-task
  workflow-without-inputs:
    tasks:
      - another-task

tasks:
  - name: sample-task
    # Declaring environment variables using inputs
    env:
      FIRST_MESSAGE: ${{ inputs.first }}
      SECOND_MESSAGE: ${{ inputs.second }}
    cubes:
      - name: sample-cube
        script:
          - echo $FIRST_MESSAGE
          - echo $SECOND_MESSAGE
  - name: another-task
    cubes:
      - name: sample-cube-2
        script:
          - echo "Hello world!"
```

#### Useful links {#see-also}

* [Workflows](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md)
* [Tasks](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.md)
* [Continuous integration and continuous deployment in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md)
* [Configuring CI/CD in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/ci-cd.md)