on

on.<event_name>.types

Use on.<event_name>.types to specify the type of a merge request (MR) event that can trigger a pipeline.

If you do not define a type, the pipeline will be triggered when an MR is opened, synchronized, or reopened. The following example shows the syntax for triggering a pipeline when an MR is closed.

1
2
3
4

on:
  pull_request:
    types:
      - closed

on.<pull_request>.<branches|branches-ignore>

Use the pull_request event to define a pipeline to run for MRs that target specific branches.

• branches: Use branches to include specific branches, or both include and exclude specific branches.
• branches-ignore: Use branches-ignore to exclude specific branches.

NOTE:

Do not use branches and branches-ignore for a pull_request event at the same time.

branches and branches-ignore support the use of glob patterns to match branch names.

Example

• Including branches

  on:
    pull_request:
      branches:
        - master
        - 'release**'

  This example indicates that the pipeline would run when there is a pull_request event that targets the following branches:

  • a branch named master, or;
  • a branch whose name starts with release, for example, release, release-1.0.0, and release/1.0.0
• Excluding branches

  on:
    pull_request:
      branches-ignore:
        - test
        - 'dev**'

  This example indicates that the pipeline would run when there is a pull_request event, unless the event targets the following branches:

  • a branch named test, or;
  • a branch whose name starts with dev, for example, dev, develop-1.0.0, and develop/1.0.0
• Both including and excluding branches
  Use branches and an exclamation mark (!) to both include and exclude specific branches.

  on:
    pull_request:
      branches:
        - 'release**'
        - '!release/v1**'

  This example indicates that the pipeline would run when there is a pull_request event, and the event's targeting branches meet all of the following conditions:

  • a branch whose name starts with release, for example, release, release-1.0.0, and release/1.0.0.
  • a branch whose name does not start with release/v1/**, for example, release/v1, release/v1.0, and release/v1/1.0.

on.<push>.<branches|branches-ignore|tags|tags-ignore>

Use the push event to define a pipeline to run on specific branches or tags.

• branches: Use branches to include specific branches, or both include and exclude specific branches.
• branches-ignore: Use branches-ignore to exclude specific branches.
• tags: Use tags to include specific tags, or both include and exclude specific tags.
• tags-ignore: Use tags-ignore to exclude specific tags.

NOTE:

• Do not use branches and branches-ignore for a push event at the same time.
• Do not use tags and tags-ignore for a push event at the same time.

Example

• Including branches/tags

  on:
    push:
      branches:
        - master
        - 'release**'
      tags:
        - v1
        - 'v2.*'

  This example indicates that the pipeline would run when there is a push event that targets the following branches and tags:

  • a branch named master, or;
  • a branch whose name starts with release, for example, release, release-1.0.0, and release/1.0.0
  • a tag named v1
  • a tag whose name starts with v2., for example, v2.1 and v2.1.1
• Excluding branches/tags

  on:
    push:
      branches-ignore:
        - test
        - 'dev**'
      tags-ignore:
        - v1
        - 'v2.*'

  This example indicates that the pipeline would run when there is a push event, unless the event targets the following branches and tags:

  • a branch named test, or;
  • a branch whose name starts with dev, for example, dev, develop-1.0.0, and develop/1.0.0.
  • a tag named v1
  • a tag whose name starts with v2., for example, v2.1 and v2.1.1
• Both including and excluding branches/tags
  Use branches, tags, and an exclamation mark (!) to both include and exclude specific branches and tags.

  on:
    push:
      branches:
        - 'release**'
        - '!release/v1**'
      tags:
        - 'v1**'
        - '!v1.1'

  This example indicates that the pipeline would run when there is a push event, and the event's targeting branches and tags meet all of the following conditions:

  • a branch whose name starts with release, for example, release, release-1.0.0, and release/1.0.0
  • a branch whose name does not start with release/v1/**, for example, release/v1, release/v1.0, and release/v1/1.0
  • a tag whose name starts with v1, for example, v1 and v1.2
  • a tag whose name is not v1.1

on.<push|pull_request>.<paths|paths-ignore>

Use the push and pull_request events to define a pipeline to run when specified files change.

• paths: Use paths to include specific files or both include and exclude specific files.
• paths-ignore: Use paths-ignore to exclude specific files.

NOTE:

Do not use paths and paths-ignore for push and pull_request events at the same time.

Example

• Including files

  on:
    push:
      paths:
        - '**.java'

  This example indicates that the pipeline would run when you push a .java file.

• Excluding files

  on:
    push:
      paths-ignore:
        - 'docs/**'

  This example indicates that the pipeline would run when there is a push event, unless all pushed files are in the docs directory.

• Both including and excluding files

  Use paths and an exclamation mark (!) to both include and exclude specific files.

  on:
    push:
      paths:
        - 'src/**'
        - '!src/docs/**'

  This example indicates that the pipeline would run when the changed files are in the src directory or its subdirectories, but not in the src/docs directory.

on.schedule

Use on.schedule to schedule a pipeline to run at a specified UTC time by defining a cron expression. The pipeline will run based on the lasted scheduled task information. To update the scheduled task, edit YAML and save it. The default branch of the pipeline source is used.

on:
  schedule:
    - cron:  '0 0 12 * * ?'
    - cron:  '0 0 20 * * ?'

The above example indicates that the pipeline would run at 12:00 and 20:00 (UTC time) every day.