Triggers

Triggers define what causes a Jenkins job to start building.

Component: triggers
Macro:

trigger

Entry Point:

jenkins_jobs.triggers

Example:

job:
  name: test_job

  triggers:
    - timed: '@daily'
class triggers.Triggers(registry)
component_list_type = 'triggers'

The component list type will be used to look up possible implementations of the component type via entry points (entry points provide a list of components, so it should be plural). Set both component_type and component_list_type to None if module doesn’t have components.

component_type = 'trigger'

The component type for components of this module. This will be used to look for macros (they are defined singularly, and should not be plural). Set both component_type and component_list_type to None if module doesn’t have components.

gen_xml(xml_parent, data)

Update the XML element tree based on YAML data. Override this method to add elements to the XML output. Create new Element objects and add them to the xml_parent. The YAML data structure must not be modified.

:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure

sequence = 50

The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.

artifactory()

Artifactory trigger. Trigger if files are added or modified in configured path(s) to watch on chosen Artifactory server.

Requires the Jenkins Artifactory Plugin.

Parameters:
  • artifactory-server (str) – Artifactory server where the configured path(s) are monitored from. Available Artifactory servers must be configured on Jenkins Global Configuration in advance. (default ‘’)

  • schedule (str) – cron syntax of when to poll. (default ‘’)

  • paths (str) – Paths in Artifactory to poll for changes. Multiple paths can be configured by the ‘;’ separator. (default ‘’)

Example with Single Path to Monitor:

triggers:
  - artifactory:
        artifactory-server: my-artifactory
        schedule: H/15 * * * *
        paths: myrepo/myfolder/latest

Example with Multiple Paths to Monitor:

triggers:
  - artifactory:
        artifactory-server: my-artifactory
        schedule: H 0,8,16 * * *
        paths: myrepo/myfolder/latest;myrepo/myfolder/commit
bitbucket()

Trigger a job when bitbucket repository is pushed to.

Requires the Jenkins BitBucket Plugin.

Example:

triggers:
  - bitbucket
build-result()

Configure jobB to monitor jobA build result. A build is scheduled if there is a new build result that matches your criteria (unstable, failure, …).

Requires the Jenkins BuildResultTrigger Plugin.

Parameters:
  • groups (list) – List groups of jobs and results to monitor for

  • jobs (list) – The jobs to monitor (required)

  • results (list) – Build results to monitor for (default success)

  • combine (bool) – Combine all job information. A build will be scheduled only if all conditions are met (default false)

  • cron (str) – The cron syntax with which to poll the jobs for the supplied result (default ‘’)

Full Example:

triggers:
  - build-result:
      cron: H/15 * * * *
      combine: true
      groups:
        - jobs:
            - test
            - test2
          results:
            - success
            - not-built
        - jobs:
            - test3
          results:
            - unstable
        # Use default results (success):
        - jobs:
            - test4

Minimal Example:

triggers:
  - build-result:
       groups:
        - jobs:
            - test
          results:
            - aborted
dockerhub-notification()

The job will get triggered when Docker Hub/Registry notifies that Docker image(s) used in this job has been rebuilt.

Requires the Jenkins CloudBees Docker Hub Notification.

Parameters:
  • referenced-image (bool) – Trigger the job based on repositories used by any compatible docker plugin in this job. (default true)

  • repositories (list) – Specified repositories to trigger the job. (default [])

Minimal Example:

triggers:
  - dockerhub-notification

Full Example:

triggers:
  - dockerhub-notification:
      referenced-image: true
      repositories:
        - repo1
        - repo2
generic-webhook-trigger()

Generic webhook trigger. Trigger when a set of parameters are submitted.

Requires the Jenkins Generic Webhook Trigger.

Parameters:
  • token (str) – A token to use to trigger the job. (default ‘’)

  • token-credential-id (str) – A token credential id to use to trigger the job. (default ‘’)

  • print-post-content (bool) – Print post content in job log.

  • print-contrib-var (bool) – Print contributed variables in job log.

  • silent-response (bool) – Avoid responding with information about triggered jobs.

  • cause (str) – This will be displayed in any triggered job.

  • regex-filter-expression (str) – Regular expression to test on the evaluated text specified in regex-filter-text

  • regex-filter-text (str) – Text to test for the given regexp-filter-expression.

  • post-content-params (list) –

    Parameters to use from posted JSON/XML

    post-content-params:
    • type (str) – JSONPath or XPath

    • key (str) – Variable name

    • value (str) – Expression to evaluate in POST content. Use JSONPath for JSON or XPath for XML.

    • regex-filter (str) – Anything in the evaluated value, matching this regular expression, will be removed. (optional)

    • default-value (str) – This value will be used if expression does not match anything. (optional)

  • request-params (list) –

    Parameters to use passed in as request arguments

    request-params:
    • key (str) – Name of request parameter

    • regex-filter (str) – Anything in the evaluated value, matching this regular expression, will be removed. (optional)

  • header-params (list) –

    Parameters to use passed in as headers

    header-params:
    • key (str) – Name of request header in lowercase. Resulting variable name has ‘_’ instead of ‘-’ characters.

    • regex-filter (str) – Anything in the evaluated value, matching this regular expression, will be removed. (optional)

Example:

triggers:
  - generic-webhook-trigger:
        post-content-params:
            - type: JSONPath
              key: action
              value: $.action
              regex-filter: value_filter
              default-value: default_value
            - type: XPath
              key: blah
              value: whooga
              regex-filter: value_filer
              default-value: default_something
        regex-filter-text: $action
        regex-filter-expression: ^(opened|reopened|synchronize)$
        request-params:
            - key: request_test_1
              regex-filter: requesT_value_1
        header-params:
            - key: header_test1
              regex-filter: header_value1
        print-post-content: true
        print-contrib-var: true
        cause: Generic Cause
        token: blah
        token-credential-id: token_credential_id
        silent-response: true
gerrit()

Trigger on a Gerrit event.

Requires the Jenkins Gerrit Trigger Plugin version >= 2.6.0.

Parameters:
  • trigger-on (list) –

    Events to react on. Please use either the new trigger-on, or the old trigger-on-* events definitions. You cannot use both at once.

    Trigger on:
    • patchset-created-event (dict) – Trigger upon patchset creation.

      Patchset created:
      • exclude-drafts (bool) – exclude drafts (default false)

      • exclude-trivial-rebase (bool) – exclude trivial rebase (default false)

      • exclude-no-code-change (bool) – exclude no code change (default false)

      • exclude-private (bool) – exclude private change (default false)

      • exclude-wip (bool) – exclude wip change (default false)

      • commit-message-contains-regex (str) – Commit message contains regular expression. (default ‘’) Requires Gerrit Trigger Plugin >= 2.32.0

      exclude-private|exclude-wip needs Gerrit Trigger v2.29.0 Exclude drafts|trivial-rebase|no-code-change needs Gerrit Trigger v2.12.0

    • patchset-uploaded-event – Trigger upon patchset creation (this is a alias for patchset-created-event).

      Deprecated since version 1.1.0: Please use trigger-on.

    • change-abandoned-event – Trigger on patchset abandoned. Requires Gerrit Trigger Plugin version >= 2.8.0.

    • change-merged-event – Trigger on change merged

    • change-restored-event – Trigger on change restored. Requires Gerrit Trigger Plugin version >= 2.8.0

    • draft-published-event – Trigger on draft published event.

    • ref-updated-event – Trigger on ref-updated. Gerrit Trigger Plugin version >= 2.29.0

    • topic-changed-event – Trigger on topic-changed. Gerrit Trigger Plugin version >= 2.26.0

    • private-state-changed-event – Trigger on private state changed event.

    • wip-state-changed-event – Trigger on wip state changed event. Gerrit Trigger Plugin version >= 2.8.0

    • comment-added-event (dict) – Trigger on comment added.

      Comment added:
      • approval-category (str) – Approval (verdict) category (for example ‘APRV’, ‘CRVW’, ‘VRIF’ – see Gerrit access control

      • approval-value – Approval value for the comment added.

    • comment-added-contains-event (dict) – Trigger on comment added contains Regular Expression.

      Comment added contains:
      • comment-contains-value (str) – Comment contains Regular Expression value.

  • trigger-on-patchset-uploaded-event (bool) –

    Trigger on patchset upload.

    Deprecated since version 1.1.0.: Please use trigger-on.

  • trigger-on-change-abandoned-event (bool) –

    Trigger on change abandoned. Requires Gerrit Trigger Plugin version >= 2.8.0

    Deprecated since version 1.1.0.: Please use trigger-on.

  • trigger-on-change-merged-event (bool) –

    Trigger on change merged

    Deprecated since version 1.1.0.: Please use trigger-on.

  • trigger-on-change-restored-event (bool) –

    Trigger on change restored. Requires Gerrit Trigger Plugin version >= 2.8.0

    Deprecated since version 1.1.0.: Please use trigger-on.

  • trigger-on-comment-added-event (bool) –

    Trigger on comment added

    Deprecated since version 1.1.0.: Please use trigger-on.

  • trigger-on-draft-published-event (bool) –

    Trigger on draft published event

    Deprecated since version 1.1.0: Please use trigger-on.

  • trigger-on-ref-updated-event (bool) –

    Trigger on ref-updated

    Deprecated since version 1.1.0.: Please use trigger-on.

  • trigger-approval-category (str) –

    Approval category for comment added

    Deprecated since version 1.1.0.: Please use trigger-on.

  • trigger-approval-value (int) –

    Approval value for comment added

    Deprecated since version 1.1.0.: Please use trigger-on.

  • override-votes (bool) – Override default vote values

  • gerrit-build-started-verified-value (int) – Started ‘’Verified’’ value

  • gerrit-build-successful-verified-value (int) – Successful ‘’Verified’’ value

  • gerrit-build-failed-verified-value (int) – Failed ‘’Verified’’ value

  • gerrit-build-unstable-verified-value (int) – Unstable ‘’Verified’’ value

  • gerrit-build-notbuilt-verified-value (int) – Not built ‘’Verified’’ value

  • gerrit-build-aborted-verified-value (int) – Aborted ‘’Verified’’ value Requires Gerrit Trigger Plugin version >= 2.31.0

  • gerrit-build-started-codereview-value (int) – Started ‘’CodeReview’’ value

  • gerrit-build-successful-codereview-value (int) – Successful ‘’CodeReview’’ value

  • gerrit-build-failed-codereview-value (int) – Failed ‘’CodeReview’’ value

  • gerrit-build-unstable-codereview-value (int) – Unstable ‘’CodeReview’’ value

  • gerrit-build-notbuilt-codereview-value (int) – Not built ‘’CodeReview’’ value

  • gerrit-build-aborted-codereview-value (int) – Aborted ‘’CodeReview’’ value Requires Gerrit Trigger Plugin version >= 2.31.0

  • failure-message (str) – Message to leave on failure (default ‘’)

  • successful-message (str) – Message to leave on success (default ‘’)

  • unstable-message (str) – Message to leave when unstable (default ‘’)

  • notbuilt-message (str) – Message to leave when not built (default ‘’)

  • aborted-message (str) – Message to leave when aborted (default ‘’)

  • failure-message-file (str) – Sets the filename within the workspace from which to retrieve the unsuccessful review message. (optional)

  • projects (list) –

    list of projects to match

    Project:
    • project-compare-type (str) – ‘’PLAIN’’, ‘’ANT’’ or ‘’REG_EXP’’

    • project-pattern (str) – Project name pattern to match

    • branch-compare-type (str) – ‘’PLAIN’’, ‘’ANT’’ or ‘’REG_EXP’’ (not used if branches list is specified)

      Deprecated since version 1.1.0: Please use branches.

    • branch-pattern (str) – Branch name pattern to match (not used if branches list is specified)

      Deprecated since version 1.1.0: Please use branches.

    • branches (list) – List of branches to match (optional)

      Branch:
      • branch-compare-type (str) – ‘’PLAIN’’, ‘’ANT’’ or ‘’REG_EXP’’ (optional) (default ‘’PLAIN’’)

      • branch-pattern (str) – Branch name pattern to match

    • file-paths (list) – List of file paths to match (optional)

      File Path:
      • compare-type (str) – ‘’PLAIN’’, ‘’ANT’’ or ‘’REG_EXP’’ (optional) (default ‘’PLAIN’’)

      • pattern (str) – File path pattern to match

    • forbidden-file-paths (list) – List of file paths to skip triggering (optional)

      Forbidden File Path:
      • compare-type (str) – ‘’PLAIN’’, ‘’ANT’’ or ‘’REG_EXP’’ (optional) (default ‘’PLAIN’’)

      • pattern (str) – File path pattern to match

    • topics (list) – List of topics to match (optional)

      Topic:
      • compare-type (str) – ‘’PLAIN’’, ‘’ANT’’ or ‘’REG_EXP’’ (optional) (default ‘’PLAIN’’)

      • pattern (str) – Topic name pattern to match

    • disable-strict-forbidden-file-verification (bool) –

      Enabling this option will allow an event to trigger a build if the event contains BOTH one or more wanted file paths AND one or more forbidden file paths. In other words, with this option, the build will not get triggered if the change contains only forbidden files, otherwise it will get triggered. Requires plugin version >= 2.16.0 (default false)

  • skip-vote (dict) –

    map of build outcomes for which Jenkins must skip vote. Requires Gerrit Trigger Plugin version >= 2.7.0

    Outcome:
    • successful (bool)

    • failed (bool)

    • unstable (bool)

    • notbuilt (bool)

    • aborted (bool) – Requires Gerrit Trigger Plugin version >= 2.31.0

  • silent (bool) – When silent mode is on there will be no communication back to Gerrit, i.e. no build started/failed/successful approve messages etc. If other non-silent jobs are triggered by the same Gerrit event as this job, the result of this job’s build will not be counted in the end result of the other jobs. (default false)

  • silent-start (bool) – Sets silent start mode to on or off. When silent start mode is on there will be no ‘build started’ messages sent back to Gerrit. (default false)

  • escape-quotes (bool) – escape quotes in the values of Gerrit change parameters (default true)

  • build-cancellation-policy (dict) –

    If used, rules regarding cancellation of builds can be set with this option when patchsets of the same change comes in. This setting overrides global server configuration. If build-cancellation-policy is not present in YAML the global server configuration is used. Requires Gerrit Trigger Plugin version >= 2.32.0

    Options:
    • abort-new-patchsets (bool) – Only running jobs will be cancelled if a new patch version is pushed over (default false).

    • abort-manual-patchsets (bool) – Builds triggered manually will be aborted when a new patch set arrives (default false).

    • abort-same-topic (bool) – Builds triggered with topic will be aborted when a new patch set with the same topic arrives (default false).

  • no-name-and-email (bool) –

    Do not pass compound ‘name and email’ parameters (default false)

    Deprecated since version 3.5.0: Please use name-and-email-parameter-mode parameter.

  • readable-message (bool) –

    If parameters regarding multiline text, e.g. commit message, should be as human readable or not. If false, those parameters are Base64 encoded to keep environment variables clean. (default false)

    Deprecated since version 3.5.0: Please use commit-message-parameter-mode parameter.

  • name-and-email-parameter-mode (str) – The parameter mode for the compound “name and email” parameters (like GERRIT_PATCHSET_UPLOADER or GERRIT_CHANGE_OWNER). This can either be ‘NONE’ to avoid passing the parameter all together, ‘PLAIN’ to pass the parameter in human readable form, or ‘BASE64’ to pass the parameter in base64 encoded form (default ‘PLAIN’). Requires Gerrit Trigger Plugin version >= 2.18.0.

  • commit-message-parameter-mode (str) – The parameter mode for the GERRIT_CHANGE_COMMIT_MESSAGE parameter. This can either be ‘NONE’ to avoid passing the parameter all together, ‘PLAIN’ to pass the parameter in human readable form, or ‘BASE64’ to pass the parameter in base64 encoded form (default ‘BASE64’). Requires Gerrit Trigger Plugin version >= 2.18.0.

  • change-subject-parameter-mode (str) – The parameter mode for the GERRIT_CHANGE_SUBJECT parameter. This can either be ‘NONE’ to avoid passing the parameter all together, ‘PLAIN’ to pass the parameter in human readable form, or ‘BASE64’ to pass the parameter in base64 encoded form (default ‘PLAIN’). Requires Gerrit Trigger Plugin version >= 2.18.0.

  • comment-text-parameter-mode (str) – The parameter mode for the GERRIT_EVENT_COMMENT_TEXT parameter. This can either be ‘NONE’ to avoid passing the parameter all together, ‘PLAIN’ to pass the parameter in human readable form, or ‘BASE64’ to pass the parameter in base64 encoded form (default ‘BASE64’). Requires Gerrit Trigger Plugin version >= 2.18.0.

  • dependency-jobs (str) – All jobs on which this job depends. If a commit should trigger both a dependency and this job, the dependency will be built first. Use commas to separate job names. Beware of cyclic dependencies. (optional)

  • notification-level (str) – Defines to whom email notifications should be sent. This can either be nobody (‘NONE’), the change owner (‘OWNER’), reviewers and change owner (‘OWNER_REVIEWERS’), all interested users i.e. owning, reviewing, watching, and starring (‘ALL’) or server default (‘SERVER_DEFAULT’). (default ‘SERVER_DEFAULT’)

  • dynamic-trigger-enabled (bool) – Enable/disable the dynamic trigger (default false)

  • dynamic-trigger-url (str) – if you specify this option, the Gerrit trigger configuration will be fetched from there on a regular interval

  • trigger-for-unreviewed-patches (bool) –

    trigger patchset-created events for changes that were uploaded while connection to Gerrit was down (default false). Requires Gerrit Trigger Plugin version >= 2.11.0.

    Deprecated since version 3.5.0: Supported for Gerrit Trigger Plugin versions < 2.14.0. See Missed Events Playback Feature.

  • custom-url (str) – Custom URL for a message sent to Gerrit. Build details URL will be used if empty. (default ‘’)

  • server-name (str) – Name of the server to trigger on, or ‘’__ANY__’’ to trigger on any configured Gerrit server (default ‘__ANY__’). Requires Gerrit Trigger Plugin version >= 2.11.0

You may select one or more Gerrit events upon which to trigger. You must also supply at least one project and branch, optionally more. If you select the comment-added trigger, you should also indicate which approval category and value you want to trigger the job.

Until version 0.4.0 of Jenkins Job Builder, camelCase keys were used to configure Gerrit Trigger Plugin, instead of hyphenated-keys. While still supported, camedCase keys are deprecated and should not be used. Support for this will be removed after 1.0.0 is released.

Example:

triggers:
  - gerrit:
      trigger-on:
        - patchset-created-event:
            exclude-drafts: true
            exclude-trivial-rebase: true
            exclude-no-code-change: true
            exclude-private: true
            exclude-wip: true
            commit-message-contains-regex: "regex"
        - comment-added-event:
            approval-category: 'APRV'
            approval-value: 1
      projects:
        - project-compare-type: 'PLAIN'
          project-pattern: 'test-project'
          branches:
            - branch-compare-type: 'PLAIN'
              branch-pattern: 'master'
            - branch-compare-type: 'PLAIN'
              branch-pattern: 'stable'
          file-paths:
              - compare-type: ANT
                pattern: subdirectory/**
          topics:
              - compare-type: ANT
                pattern: refactor-xy**
      skip-vote:
          successful: true
          failed: true
          unstable: true
          notbuilt: true
          aborted: true
      build-cancellation-policy:
        abort-new-patchsets: false
        abort-manual-patchsets: true
        abort-same-topic: true
      silent: false
      silent-start: true
      escape-quotes: false
      dependency-jobs: 'job1, job2'
      name-and-email-parameter-mode: PLAIN
      notification-level: ALL
      dynamic-trigger-enabled: true
      dynamic-trigger-url: http://myhost/mytrigger
      server-name: my-server
      failure-message-file: path/to/filename
github()

Trigger a job when github repository is pushed to.

Requires the Jenkins GitHub Plugin.

Example:

triggers:
  - github
github-pull-request()

Build pull requests in github and report results.

Requires the Jenkins GitHub Pull Request Builder Plugin.

Parameters:
  • admin-list (list) – the users with admin rights (optional)

  • white-list (list) – users whose pull requests build (optional)

  • org-list (list) – orgs whose users should be white listed (optional)

  • allow-whitelist-orgs-as-admins (bool) – members of white listed orgs will have admin rights. (default false)

  • cron (str) – cron syntax of when to run (optional)

  • trigger-phrase (str) – when filled, commenting this phrase in the pull request will trigger a build (optional)

  • only-trigger-phrase (bool) – only commenting the trigger phrase in the pull request will trigger a build (default false)

  • skip-build-phrase (str) – when filled, adding this phrase to the pull request title or body will not trigger a build (optional)

  • black-list-commit-author (list) – When filled, pull request commits from this user(s) will not trigger a build (optional)

  • black-list-labels (str) – list of GitHub labels for which the build should not be triggered (optional)

  • white-list-labels (str) – list of GitHub labels for which the build should only be triggered. (Leave blank for ‘any’) (optional)

  • github-hooks (bool) – use github hook (default false)

  • permit-all (bool) – build every pull request automatically without asking (default false)

  • auto-close-on-fail (bool) – close failed pull request automatically (default false)

  • display-build-errors-on-downstream-builds (bool) – Display build errors on downstream builds (default false)

  • white-list-target-branches (list) – Adding branches to this whitelist allows you to selectively test pull requests destined for these branches only. Supports regular expressions (e.g. ‘master’, ‘feature-.*’). (optional)

  • black-list-target-branches (list) – Adding branches to this blacklist allows you to selectively prevent pull requests builds destined for these branches. Supports regular expressions (e.g. ‘master’, ‘feature-.*’). (optional)

  • auth-id (str) – the auth id to use (optional)

  • build-desc-template (str) – the template for build descriptions in jenkins (optional)

  • status-context (str) – the context to include on PR status comments (optional)

  • triggered-status (str) – the status message to set when the build has been triggered (optional)

  • started-status (str) – the status comment to set when the build has been started (optional)

  • status-url (str) – the status URL to set (optional)

  • status-add-test-results (bool) – add test result one-liner to status message (optional)

  • success-status (str) – the status message to set if the job succeeds (optional)

  • failure-status (str) – the status message to set if the job fails (optional)

  • error-status (str) – the status message to set if the job errors (optional)

  • success-comment (str) – comment to add to the PR on a successful job (optional)

  • failure-comment (str) – comment to add to the PR on a failed job (optional)

  • error-comment (str) – comment to add to the PR on an errored job (optional)

  • cancel-builds-on-update (bool) – cancel existing builds when a PR is updated (optional)

  • comment-file (str) – Extends the standard build comment message on github with a custom message file. (optional)

  • no-commit-status (bool) – Enables “Do not update commit status”

  • included-regions (list) – Each inclusion uses regular expression pattern matching, and must be separated by a new line. An empty list implies that everything is included. (optional)

  • excluded-regions (list) – Each exclusion uses regular expression pattern matching, and must be separated by a new line. Exclusions take precedence over inclusions, if there is an overlap between included and excluded regions. (optional)

Full Example:

triggers:
  - github-pull-request:
      admin-list:
        - user1
        - user2
      white-list:
        - user3
        - user4
      org-list:
        - org1
        - org2
      white-list-labels:
        - label1
        - label2
      black-list-labels:
        - label3
        - label4
      cron: '* * * * *'
      build-desc-template: "build description"
      trigger-phrase: 'retest this please'
      skip-build-phrase: 'no tests'
      black-list-commit-author:
        - blacklist
        - commit
        - author
      only-trigger-phrase: true
      github-hooks: true
      permit-all: true
      auto-close-on-fail: false
      display-build-errors-on-downstream-builds: true
      allow-whitelist-orgs-as-admins: true
      white-list-target-branches:
        - master
        - testing
      black-list-target-branches:
        - master
        - testing
      auth-id: '123-456-789'
      status-context: "status context"
      triggered-status: "triggered status message"
      started-status: "started"
      status-url: "url/to/status"
      status-add-test-results: false
      success-status: "success message"
      failure-status: "failure message"
      error-status: "error message"
      success-comment: "success comment"
      failure-comment: "failure comment"
      error-comment: "error-comment"
      cancel-builds-on-update: true
      comment-file: "/tmp/path"
      no-commit-status: true
      included-regions:
          - include
          - region
      excluded-regions:
          - exclude
          - region

Minimal Example:

triggers:
  - github-pull-request
gitlab()

Makes Jenkins act like a GitLab CI server.

Requires the Jenkins GitLab Plugin.

Parameters:
  • trigger-push (bool) – Build on Push Events (default true)

  • trigger-merge-request (bool) – Build on Merge Request Events (default true)

  • trigger-accepted-merge-request (bool) – Build on Accepted Merge Request Events (>= 1.4.6) (default false)

  • trigger-closed-merge-request (bool) – Build on Closed Merge Request Events (>= 1.4.6) (default false)

  • trigger-open-merge-request-push (str) –

    Rebuild open Merge Requests on Push Events.

    trigger-open-merge-request-push values (< 1.1.26):
    • true (default)

    • false

    trigger-open-merge-request-push values (>= 1.1.26):
    • never (default)

    • source

    • both

  • trigger-only-if-new-commits-pushed (bool) – Trigger a build on commits pushed only, but not trigger on another MR changes(label, edit, assign, etc) (>=1.5.17)(default false)

  • trigger-note (bool) – Build when comment is added with defined phrase (>= 1.2.4) (default true)

  • note-regex (str) – Phrase that triggers the build (>= 1.2.4) (default ‘Jenkins please retry a build’)

  • ci-skip (bool) – Enable skipping builds of commits that contain [ci-skip] in the commit message (default true)

  • wip-skip (bool) – Enable skipping builds of WIP Merge Requests (>= 1.2.4) (default true)

  • set-build-description (bool) – Set build description to build cause (eg. Merge request or Git Push) (default true)

  • cancel-pending-builds-on-update (bool) – Cancel pending merge request builds on update (default false)

  • pending-build-name (str) – Set the pending merge request build name (optional)

  • add-note-merge-request (bool) – Add note with build status on merge requests (default true)

  • add-vote-merge-request (bool) – Vote added to note with build status on merge requests (>= 1.1.27) (default true)

  • accept-merge-request-on-success (bool) – Automatically accept the Merge Request if the build is successful (>= 1.1.27) (default false)

  • add-ci-message (bool) – Add CI build status (1.1.28 - 1.2.0) (default false)

  • allow-all-branches (bool) – Allow all branches (Ignoring Filtered Branches) (< 1.1.29) (default false)

  • branch-filter-type (str) – Filter branches that can trigger a build. Valid values and their additional attributes are described in the branch filter type table (>= 1.1.29) (default ‘All’).

  • include-branches (list) – Defined list of branches to include (default [])

  • exclude-branches (list) – Defined list of branches to exclude (default [])

  • source-branch-regex (str) – Regular expression to select branches

  • target-branch-regex (str) – Regular expression to select branches

  • secret-token (str) – Secret token for build trigger

  • merge-request-label-filter-config (dict) –

    If used allow merge requests filtering by labels

    Options:
    • include (str) Run for specified labels.

    • exclude (str) Do not run for specified labels.

Branch filter type

Description

All

All branches are allowed to trigger this job.

NameBasedFilter

Filter branches by name. List source branches that are allowed to trigger a build from a Push event or a Merge Request event. If both fields are left empty, all branches are allowed to trigger this job. For Merge Request events only the target branch name is filtered out by the include-branches and exclude-branches lists.

RegexBasedFilter

Filter branches by regex The target branch regex allows you to limit the execution of this job to certain branches. Any branch matching the specified pattern in target-branch-regex and source-branch-regex triggers the job. No filtering is performed if the field is left empty.

Example (version < 1.1.26):

triggers:
  - gitlab:
      trigger-push: true
      trigger-merge-request: true
      trigger-open-merge-request-push: true
      ci-skip: true
      set-build-description: true
      add-note-merge-request: true
      add-vote-merge-request: true
      add-ci-message: true
      allow-all-branches: true
      include-branches:
        - 'master'
        - 'master2'
        - 'local-test'
      exclude-branches:
        - 'broken-test'
        - 'master-foo'

Minimal example (version >= 1.1.26):

triggers:
  - gitlab

Full example (version >= 1.1.26):

triggers:
  - gitlab:
      trigger-push: false
      trigger-merge-request: false
      trigger-only-if-new-commits-pushed: false
      trigger-open-merge-request-push: both
      ci-skip: false
      set-build-description: false
      add-note-merge-request: false
      add-vote-merge-request: false
      add-ci-message: true
      allow-all-branches: true
      include-branches:
        - 'master'
        - 'master2'
        - 'local-test'
      exclude-branches:
        - 'broken-test'
        - 'master-foo'
      pending-build-name: 'test'
gitlab-merge-request()

Build merge requests in gitlab and report results.

Requires the Jenkins Gitlab MergeRequest Builder Plugin.

Parameters:
  • cron (str) – Cron syntax of when to run (required)

  • project-path (str) – Gitlab-relative path to project (required)

  • target-branch-regex (str) – Allow execution of this job for certain branches only (default ‘’). Requires Gitlab MergeRequest Builder Plugin >= 2.0.0

  • use-http-url (str) – Use the HTTP(S) URL to fetch/clone repository (default false)

  • assignee-filter (str) – Only MRs with this assigned user will trigger the build automatically (default ‘jenkins’)

  • tag-filter (str) – Only MRs with this label will trigger the build automatically (default ‘Build’)

  • trigger-comment (str) – Force build if this comment is the last in merge reguest (default ‘’)

  • publish-build-progress-messages (str) –

    Publish build progress messages (except build failed) (default true)

    Deprecated since version 2.0.0.

  • auto-close-failed (str) – On failure, auto close the request (default false)

  • auto-merge-passed (str) – On success, auto merge the request (default false)

Example (version < 2.0.0):

triggers:
  - gitlab-merge-request:
      cron: '* * * * *'
      project-path: 'test/project'
      use-http-url: false
      assignee-filter: 'jenkinsbot'
      tag-filter: 'fix'
      trigger-comment: 'rebuild'
      publish-build-progress-messages: true
      auto-close-failed: false
      auto-merge-passed: false

Example (version >= 2.0.0):

triggers:
  - gitlab-merge-request:
      cron: '* * * * *'
      project-path: 'test/project'
      target-branch-regex: '(.*release.*|.*hotfix.*)'
      use-http-url: false
      assignee-filter: 'jenkinsbot'
      tag-filter: 'fix'
      trigger-comment: 'rebuild'
      auto-close-failed: false
      auto-merge-passed: false
gogs()

Trigger a job when gogs repository is pushed to.

Requires the Jenkins Gogs Plugin.

Example:

triggers:
  - gogs
groovy-script()

Triggers the job using a groovy script.

Requires the Jenkins ScriptTrigger Plugin.

Parameters:
  • system-script (bool) – If true, run the groovy script as a system script, the script will have access to the same variables as the Groovy Console. If false, run the groovy script on the executor node, the script will not have access to the hudson or job model. (default false)

  • script (str) – Content of the groovy script. If the script result is evaluated to true, a build is scheduled. (default ‘’)

  • script-file-path (str) – Groovy script path. (default ‘’)

  • property-file-path (str) – Property file path. All properties will be set as parameters for the triggered build. (default ‘’)

  • enable-concurrent (bool) – Enable concurrent build. (default false)

  • label (str) – Restrict where the polling should run. (default ‘’)

  • cron (str) – cron syntax of when to run (default ‘’)

Full Example:

triggers:
  - groovy-script:
        script: groovy-content
        script-file-path: path/to/filename
        property-file-path: /path/to/properties/file
        cron: H/15 * * * *
        enable-concurrent: true
        label: master
        system-script: true

Minimal Example:

triggers:
  - groovy-script
ivy()

Poll with an Ivy script.

Requires the Jenkins IvyTrigger Plugin.

Parameters:
  • path (str) – Path of the ivy file. (optional)

  • settings-path (str) – Ivy Settings Path. (optional)

  • properties-file (list) – List of properties file path. Properties will be injected as variables in the ivy settings file. (optional)

  • properties-content (str) – Properties content. Properties will be injected as variables in the ivy settings file. (optional)

  • debug (bool) – Active debug mode on artifacts resolution. (default false)

  • download-artifacts – Download artifacts for dependencies to see if they have changed. (default true)

  • enable-concurrent (bool) – Enable Concurrent Build. (default false)

  • label (str) – Restrict where the polling should run. (default ‘’)

  • cron (str) – cron syntax of when to run (default ‘’)

Example:

triggers:
  - ivy:
        path: path/to/file
        settings-path: path/to/settings/file
        properties-file:
            - 'filename1'
            - 'filename2'
        debug: true
        cron: 'H/15 * * * *'
        enable-concurrent: False
        label: master
jira-changelog()

Sets up a trigger that listens to JIRA issue changes.

Requires the Jenkins JIRA Trigger Plugin.

Parameters:
  • jql-filter (str) – Must match updated issues to trigger a build. (default ‘’)

  • changelog-matchers (list) –

    Custom Field Matcher:
    • custom-field-name (str) – The custom field

      name that has been changed during the issue update. (default ‘’)

    • compare-new-value (bool) – Compare the

      new value of the updated field. (default false)

    • new-value (str) – The new value of the updated field.

      (default ‘’)

    • compare-old-value (bool) – Compare the

      old value of the updated field. (default false)

    • old-value (str) – The value

      before the field is updated. (default ‘’)

    JIRA Field Matcher:
    • jira-field-ID (str) – The JIRA Field ID that

      has been changed during the issue update. (default ‘’)

    • compare-new-value (bool) – Compare the new value

      of the updated field. (default false)

    • new-value (str) – The new value of the updated field.

      (default ‘’)

    • compare-old-value (bool) – Compare the old value

      of the updated field. (default false)

    • old-value (str) – The value before

      the field is updated. (default ‘’)

  • parameter-mapping (list) –

    Issue Attribute Path:
    • jenkins-parameter (str) – Jenkins parameter name

      (default ‘’)

    • issue-attribute-path (str) – Attribute path (default ‘’)

Minimal Example:

triggers:
  - jira-changelog

Full Example:

triggers:
  - jira-changelog:
      jql-filter: filter
      changelog-matchers:
          - field-type: 'CUSTOM'
            field: name
            new-value: val1
            old-value: val2
            compare-new-value: true
            compare-old-value: true
          - field-type: 'JIRA'
            field: versions
            new-value: val3
            old-value: val4
            compare-new-value: true
            compare-old-value: true
      parameter-mapping:
          - jenkins-parameter: param
            issue-attribute-path: path
jira-comment-trigger()

Trigger builds when a comment is added to JIRA.

Requires the Jenkins JIRA Trigger Plugin.

Parameters:
  • jql-filter (str) – Must match updated issues to trigger a build. (default ‘’)

  • comment-pattern (str) – Triggers build only when the comment added to JIRA matches pattern (default ‘(?i)build this please’)

  • parameter-mapping (list) –

    Issue Attribute Path:
    • jenkins-parameter (str) – Jenkins parameter name

      (default ‘’)

    • issue-attribute-path (str) – Attribute path (default ‘’)

Minimal Example:

triggers:
  - jira-comment-trigger

Full Example:

triggers:
  - jira-comment-trigger:
      jql-filter: filter
      comment-pattern: comment
      parameter-mapping:
        - jenkins-parameter: param1
          issue-attribute-path: 'path/to/attribute'
jms-messaging()
The JMS Messaging Plugin provides the following functionality:
  • A build trigger to submit jenkins jobs upon receipt of a matching message.

  • A builder that may be used to submit a message to the topic upon the completion of a job

  • A post-build action that may be used to submit a message to the topic upon the completion of a job

JMS Messaging provider types supported:
  • ActiveMQ

  • FedMsg

Requires the Jenkins JMS Messaging Plugin.

Parameters:
  • no-squash (bool) – true = schedule a new job for every triggering message. (default false) Normally if a job is queued and another triggering message is received, a new job is not submitted and the job is “squashed” into the job already queued. Setting this option to ‘True’ forces a new job to be submitted for every triggering message that is received.

  • override-topic (str) – If you need to override the default topic. (default ‘’)

  • selector (str) – The JSON or YAML formatted text that conforms to the schema for defining the various OpenShift resources. (default ‘’) note: topic needs to be in double quotes ex. topic = “org.fedoraproject.prod.fedimg.image.upload”

  • provider-name (str) – Name of message provider setup in the global config. (default ‘’)

  • checks (list) – List of checks to monitor. (default [])

  • field (str) – Check the body of messages for a field. (default ‘’)

  • expected-value (str) – Expected value for the field. regex (default ‘’)

Full Example:

triggers:
  - jms-messaging:
      no-squash: True
      selector: topic = "org.fedoraproject.prod.fedimg.image.upload"
      provider-name: fedmsg
      checks:
        - field: compose
          expected-value: .+compose_id.+Fedora-Atomic.+
        - field: image_name
          expected-value: .+Fedora-Atomic.+

Minimal Example:

triggers:
  - jms-messaging:
      selector: topic = "org.fedoraproject.prod.fedimg.image.upload"
      provider-name: fedmsg
monitor-files()

Configure Jenkins to monitor files. Requires the Jenkins Filesystem Trigger Plugin.

Parameters:
  • files (list) –

    List of files to monitor

    File:
    • path (str) – File path to monitor. You can use a pattern that specifies a set of files if you don’t know the real file path. (required)

    • strategy (str) – Choose your strategy if there is more than one matching file. Can be one of Ignore file (‘IGNORE’) or Use the most recent (‘LATEST’). (default ‘LATEST’)

    • check-content (list) – List of content changes of the file to monitor

      Content Nature:
      • simple (bool) – Trigger on change in content of the specified file (whatever the type file). (default false)

      • jar (bool) – Trigger on change in content of the specified JAR file. (default false)

      • tar (bool) – Trigger on change in content of the specified Tar file. (default false)

      • zip (bool) – Trigger on change in content of the specified ZIP file. (default false)

      • source-manifest (list) – Trigger on change to MANIFEST files.

        MANIFEST File:
        • keys (list) – List of keys to inspect. (optional)

        • all-keys (bool) – If true, take into account all keys. (default true)

      • jar-manifest (list) – Trigger on change to MANIFEST files (contained in jar files).

        MANIFEST File:
        • keys (list) – List of keys to inspect. (optional)

        • all-keys (bool) – If true, take into account all keys. (default true)

      • properties (list) – Monitor the contents of the properties file.

        Properties File:
        • keys (list) – List of keys to inspect. (optional)

        • all-keys (bool) – If true, take into account all keys. (default true)

      • xml (list str) – Trigger on change to the listed XPath expressions.

      • text (list str) – Trigger on change to the listed regular expressions.

    • ignore-modificaton-date (bool) – If true, ignore the file modification date. Only valid when content changes of the file are being monitored. (default true)

  • cron (str) – cron syntax of when to run (default ‘’)

Minimal Example:

triggers:
  - monitor-files:
      files:
          - path: 'path1'

Full Example:

triggers:
  - monitor-files:
      cron: '* * * * *'
      files:
          - path: 'path1'
            strategy: 'IGNORE'
          - path: 'path2'
            check-content:
                - simple: true
                - jar: true
                - tar: true
                - zip: true
                - source-manifest:
                    - all-keys: false
                      keys:
                          - key1
                          - key2
                - jar-manifest:
                    - keys:
                          - key1
                          - key2
                - properties:
                    - all-keys: false
                      keys:
                          - prop1
                          - prop2
                - xml:
                    - 'xpath1'
                    - 'xpath2'
                - text:
                    - 'regex1'
            ignore-modificaton-date: false
monitor-folders()

Configure Jenkins to monitor folders.

Requires the Jenkins Filesystem Trigger Plugin.

Parameters:
  • path (str) – Folder path to poll. (default ‘’)

  • includes (list) – Fileset includes setting that specifies the list of includes files. Basedir of the fileset is relative to the workspace root. If no value is set, all files are used. (default ‘’)

  • excludes (str) – The ‘excludes’ pattern. A file that matches this mask will not be polled even if it matches the mask specified in ‘includes’ section. (default ‘’)

  • check-modification-date (bool) – Check last modification date. (default true)

  • check-content (bool) – Check content. (default true)

  • check-fewer (bool) – Check fewer files (default true)

  • cron (str) – cron syntax of when to run (default ‘’)

Full Example:

triggers:
  - monitor-folders:
      path: 'pathname'
      includes:
        - 'pattern1'
        - 'pattern2'
      excludes: 'pattern1'
      check-modification-date: false
      check-content: false
      check-fewer: false
      cron: H/15 * * * *

Minimal Example:

triggers:
  - monitor-folders
parameterized-timer()

Trigger builds with parameters at certain times. Requires the Jenkins Parameterized Scheduler Plugin.

Parameters:

cron (str) – cron syntax of when to run and with which parameters (required)

Example:

triggers:
  - parameterized-timer:
      cron: "@midnight % PARAM=value"
pollscm()

Poll the SCM to determine if there has been a change.

Parameter:

the polling interval (cron syntax)

Deprecated since version 1.3.0.: Please use cron.

Parameters:
  • cron (str) – the polling interval (cron syntax, required)

  • ignore-post-commit-hooks (bool) – Ignore changes notified by SCM post-commit hooks. The subversion-plugin supports this since version 1.44. (default false)

Example:

triggers:
  - pollscm:
      cron: "*/30 * * * *"
      ignore-post-commit-hooks: True
pollurl()

Trigger when the HTTP response from a URL changes. Requires the Jenkins URLTrigger Plugin.

Parameters:
  • cron (str) – cron syntax of when to run (default ‘’)

  • polling-node (str) – Restrict where the polling should run. (optional)

  • urls (list) –

    List of URLs to monitor

    URL:
    • url (str) – URL to monitor for changes (required)

    • proxy (bool) – Activate the Jenkins proxy (default false)

    • timeout (int) – Connect/read timeout in seconds (default 300)

    • username (str) – User name for basic authentication (optional)

    • password (str) – Password for basic authentication (optional)

    • check-status (int) – Check for a specific HTTP status code (optional)

    • check-etag (bool) – Check the HTTP ETag for changes (default false)

    • check-date (bool) – Check the last modification date of the URL (default false)

    • check-content (list) – List of content type changes to monitor

      Content Type:
      • simple (bool) – Trigger on any change to the content of the URL (default false)

      • json (list) – Trigger on any change to the listed JSON paths

      • text (list) – Trigger on any change to the listed regular expressions

      • xml (list) – Trigger on any change to the listed XPath expressions

Example:

triggers:
  - pollurl:
      cron: '* * * * *'
      polling-node: 'label expression'
      urls:
        - url: 'http://example.com/url1'
          proxy: false
          timeout: 442
          username: username
          password: sekr3t
          check-status: 202
          check-etag: false
          check-date: true
          check-content:
            - simple: true
            - json:
              - '$..author'
              - '$.store..price'
        - url: 'http://example.com/url2'
          proxy: true
          check-etag: true
          check-content:
            - simple: false
            - xml:
              - '//author'
              - '/store//price'
            - text:
              - '\d+'
rabbitmq()

This plugin triggers build using remote build message in RabbitMQ queue.

Requires the Jenkins RabbitMQ Build Trigger Plugin.

Parameters:
  • token (str) – the build token expected in the message queue (required)

  • filters (list) –

    list of filters to apply (optional)

    Filter:
    • field (str) - Some field in message (required)

    • value (str) - value of specified field (required)

Example:

triggers:
  - rabbitmq:
      token: 'build_trigger_token'

Example with filters:

triggers:
  - rabbitmq:
      token: 'build_trigger_token'
      filters:
        - field: 'field1'
          value: 'value1'
        - field: 'field2'
          value: 'value2'
reverse()

This trigger can be configured in the UI using the checkbox with the following text: ‘Build after other projects are built’.

Set up a trigger so that when some other projects finish building, a new build is scheduled for this project. This is convenient for running an extensive test after a build is complete, for example.

This configuration complements the “Build other projects” section in the “Post-build Actions” of an upstream project, but is preferable when you want to configure the downstream project.

Parameters:
  • jobs (str) – List of jobs to watch. Can be either a comma separated list or a list.

  • result (str) – Build results to monitor for between the following options: success, unstable and failure. (default ‘success’).

Example:

triggers:
  - reverse:
        jobs: 'Fantastic-job'
        result: 'failure'

Example List:

triggers:
  - reverse:
        jobs:
            - 'a'
            - 'b'
            - 'c'
        result: 'failure'
script()

Triggers the job using shell or batch script.

Requires the Jenkins ScriptTrigger Plugin.

Parameters:
  • label (str) – Restrict where the polling should run. (default ‘’)

  • script (str) – A shell or batch script. (default ‘’)

  • script-file-path (str) – A shell or batch script path. (default ‘’)

  • cron (str) – cron syntax of when to run (default ‘’)

  • enable-concurrent (bool) – Enables triggering concurrent builds. (default false)

  • exit-code (int) – If the exit code of the script execution returns this expected exit code, a build is scheduled. (default 0)

Full Example:

triggers:
  - script:
        script: 'exit 0'
        script-file-path: '$WORKSPACE/scripts'
        cron: 'H/15 * * * *'
        enable-concurrent: true
        label: master
        exit-code: 0

Minimal Example:

triggers:
  - script
stash-pull-request()

Trigger builds via Stash/Bitbucket Server Pull Requests.

Requires the Jenkins Stash Pull Request Builder Plugin.

arg str cron:

cron syntax of when to run (required)

arg str stash-host:

The HTTP or HTTPS URL of the Stash host (NOT ssh). e.g.: https://example.com (required)

arg str credentials-id:

Jenkins credential set to use. (required)

arg str project:

Abbreviated project code. e.g.: PRJ or ~user (required)

arg str repository:

Stash Repository Name. e.g.: Repo (required)

arg str ci-skip-phrases:

CI Skip Phrases. (default ‘NO TEST’)

arg str ci-build-phrases:

CI Build Phrases. (default ‘test this please’)

arg str target-branches:

Target branches to filter. (default ‘’)

arg bool ignore-ssl:

Ignore SSL certificates for Stash host. (default false)

arg bool check-destination-commit:

Rebuild if destination branch changes. (default false)

arg bool check-mergable:

Build only if PR is mergeable. (default false)

arg bool merge-on-success:

Merge PR if build is successful. (default false)

arg bool check-not-conflicted:

Build only if Stash reports no conflicts. (default false)

arg bool only-build-on-comment:

Only build when asked (with test phrase). (default false)

arg bool delete-previous-build-finish-comments:

Keep PR comment only for most recent Build. (default false)

arg bool cancel-outdated-jobs:

Cancel outdated jobs. (default false)

Minimal Example:

triggers:
  - stash-pull-request:
      cron: "* * * * *"
      stash-host: "https://stash-host.com"
      credentials-id: default-stash-credentials
      project: stash-project
      repository: stash-repo

Full Example:

triggers:
  - stash-pull-request:
      cron: "H 1 2 3 4"
      stash-host: "https://stash-host.com"
      credentials-id: default-stash-credentials
      project: stash-project
      repository: stash-repo
      ci-skip-phrases: "test skip phrase"
      ci-build-phrases: "test build phrase"
      target-branches: "master"
      ignore-ssl: true
      check-destination-commit: true
      check-mergable: true
      merge-on-success: true
      check-not-conflicted: false
      only-build-on-comment: true
      delete-previous-build-finish-comments: true
      cancel-outdated-jobs: true
timed()

Trigger builds at certain times.

Parameter:

when to run the job (cron syntax)

Example:

triggers:
  - timed: "@midnight"