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'
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 ‘’)

Example:

triggers:
  - build-result:
      combine: true
      cron: '* * * * *'
      groups:
        - jobs:
            - foo
            - example
          results:
            - unstable
        - jobs:
            - foo2
          results:
            - not-built
            - aborted
gerrit

Trigger on a Gerrit event. Requires the Jenkins Gerrit Trigger Plugin version >= 2.6.0.

Parameters:
  • trigger-on-patchset-uploaded-event (bool) – Trigger on patchset upload
  • trigger-on-change-abandoned-event (bool) – Trigger on change abandoned. Requires Gerrit Trigger Plugin version >= 2.8.0
  • trigger-on-change-merged-event (bool) – Trigger on change merged
  • trigger-on-change-restored-event (bool) – Trigger on change restored. Requires Gerrit Trigger Plugin version >= 2.8.0
  • trigger-on-comment-added-event (bool) – Trigger on comment added
  • trigger-on-draft-published-event (bool) – Trigger on draft published event
  • trigger-on-ref-updated-event (bool) – Trigger on ref-updated
  • trigger-approval-category (str) – Approval category for comment added
  • trigger-approval-value (int) – Approval value for comment added
  • override-votes (bool) – Override default vote values
  • gerrit-build-successful-verified-value (int) – Successful ‘’Verified’’ value
  • gerrit-build-failed-verified-value (int) – Failed ‘’Verified’’ value
  • gerrit-build-successful-codereview-value (int) – Successful ‘’CodeReview’’ value
  • gerrit-build-failed-codereview-value (int) – Failed ‘’CodeReview’’ value
  • 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 ‘’)
  • 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)
    • branch-pattern (str) – Branch name pattern to match
      (not used if branches list is specified)
    • 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
    • topics (list) – List of topics to match (optional)
      File Path:
      • compare-type (str) – ‘’PLAIN’‘, ‘’ANT’’ or ‘’REG_EXP’’ (optional) (default ‘’PLAIN’‘)
      • pattern (str) – Topic name pattern to match
  • 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)
  • 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)
  • escape-quotes (bool) – escape quotes in the values of Gerrit change parameters (default true)
  • no-name-and-email (bool) – Do not pass compound ‘name and email’ parameters (default false)
  • 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
  • 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.

Example:

triggers:
  - gerrit:
      trigger-on-comment-added-event: true
      trigger-approval-category: 'APRV'
      trigger-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
      silent: false
      escape-quotes: false
      no-name-and-email: false
      dynamic-trigger-enabled: true
      dynamic-trigger-url: http://myhost/mytrigger
      trigger-for-unreviewed-patches: true
      server-name: my-server
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)
  • cron (string) – cron syntax of when to run (optional)
  • trigger-phrase (string) – 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)
  • 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)

Example:

triggers:
  - github-pull-request:
      admin-list:
        - user1
        - user2
      white-list:
        - user3
        - user4
      org-list:
        - org1
        - org2
      cron: '* * * * *'
      trigger-phrase: 'retest this please'
      only-trigger-phrase: true
      github-hooks: true
      permit-all: false
      auto-close-on-fail: false
gitlab-merge-request

Build merge requests in gitlab and report results. Requires the Jenkins Gitlab MergeRequest Builder Plugin.

Parameters:
  • cron (string) – cron syntax of when to run (required)
  • project-path (string) – gitlab-relative path to project (required)

Example:

triggers:
  - gitlab-merge-request:
      cron: '* * * * *'
      project-path: 'test/project'
pollscm

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

Parameter:the polling interval (cron syntax)

Example:

triggers:
  - pollscm: "\*/15 * * * \*"
pollurl

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

Parameters:
  • cron (string) – cron syntax of when to run (default ‘’)
  • polling-node (string) – 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 (string) – User name for basic authentication (optional)
    • password (string) – 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+'
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 (comma separated) of jobs to watch.
  • 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'
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 ‘’)
  • 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)

Example:

triggers:
  - script:
        script: 'exit 0'
        cron: 'H/15 * * * *'
        enable-concurrent: False
        label: master
        exit-code: 0
timed

Trigger builds at certain times.

Parameter:when to run the job (cron syntax)

Example:

triggers:
  - timed: "@midnight"

Previous topic

SCM

Next topic

Wrappers

This Page