Publishers

Publishers define actions that the Jenkins job should perform after the build is complete.

Component: publishers
Macro:publisher
Entry Point:jenkins_jobs.publishers

Example:

job:
  name: test_job

  publishers:
    - scp:
        site: 'example.com'
        source: 'doc/build/html/**/*'
        target_path: 'project'
aggregate-tests

Aggregate downstream test results

Parameters:include-failed-builds (bool) – whether to include failed builds

Example:

publishers:
  - aggregate-tests:
      include-failed-builds: true
archive

Archive build artifacts

Parameters:
  • artifacts (str) – path specifier for artifacts to archive
  • excludes (str) – path specifier for artifacts to exclude
  • latest-only (bool) – only keep the artifacts from the latest successful build

Example:

publishers:
  - archive:
      artifacts: '*.tar.gz'
checkstyle

Publish trend reports with Checkstyle. Requires the Checkstyle Plugin.

The checkstyle component accepts a dictionary with the following values:

Parameters:
  • pattern (str) – report filename pattern
  • canRunOnFailed (bool) – also runs for failed builds (instead of just stable or unstable builds)
  • shouldDetectModules (bool) –
  • healthy (int) – sunny threshold
  • unHealthy (int) – stormy threshold
  • healthThreshold (str) – threshold priority for health status (high: only high, normal: high and normal, low: all)
  • thresholds (dict) –
    thresholds:
    • unstable (dict)
      unstable:
      • totalAll (int)
      • totalHigh (int)
      • totalNormal (int)
      • totalLow (int)
    • failed (dict)
      failed:
      • totalAll (int)
      • totalHigh (int)
      • totalNormal (int)
      • totalLow (int)
  • defaultEncoding (str) – encoding for parsing or showing files (empty will use platform default)

Example:

publishers:
  - checkstyle:
      pattern: '**/checkstyle-result.xml'
      healthy: 0
      unHealthy: 100
      healthThreshold: 'high'
      thresholds:
          unstable:
              totalHigh: 10
          failed:
              totalHigh: 1
cifs

Upload files via CIFS. Requires the Jenkins Publish over CIFS Plugin.

Parameters:
  • site (str) – name of the cifs site/share
  • target (str) – destination directory
  • target-is-date-format (bool) – whether target is a date format. If true, raw text should be quoted (defaults to False)
  • clean-remote (bool) – should the remote directory be deleted before transfering files (defaults to False)
  • source (str) – source path specifier
  • excludes (str) – excluded file pattern (optional)
  • remove-prefix (str) – prefix to remove from uploaded file paths (optional)
  • fail-on-error (bool) – fail the build if an error occurs (defaults to False).

Example:

publishers:
  - cifs:
      site: 'cifs.share'
      target: 'dest/dir'
      source: 'base/source/dir/**'
      remove-prefix: 'base/source/dir'
      excludes: '**/*.excludedfiletype'
claim-build

Claim build failures Requires the Jenkins Claim Plugin.

Example:

publishers:
  - claim-build
cobertura

Generate a cobertura coverage report. Requires the Jenkins Cobertura Coverage Plugin.

Parameters:
  • report-file (str) – This is a file name pattern that can be used to locate the cobertura xml report files (optional)
  • only-stable (bool) – Include only stable builds (default false)
  • fail-no-reports (bool) – fail builds if no coverage reports are found (default false)
  • fail-unhealthy (bool) – Unhealthy projects will be failed (default false)
  • fail-unstable (bool) – Unstable projects will be failed (default false)
  • health-auto-update (bool) – Auto update threshold for health on successful build (default false)
  • stability-auto-update (bool) – Auto update threshold for stability on successful build (default false)
  • zoom-coverage-chart (bool) – Zoom the coverage chart and crop area below the minimum and above the maximum coverage of the past reports (default false)
  • source-encoding (str) – Override the source encoding (default ASCII)
  • targets (dict) –
    targets:(packages, files, classes, method, line, conditional)
    • healthy (int): Healthy threshold (default 0)
    • unhealthy (int): Unhealthy threshold (default 0)
    • failing (int): Failing threshold (default 0)

Example:

publishers:
  - cobertura:
       report-file: "/reports/cobertura/coverage.xml"
       only-stable: "true"
       fail-no-reports: "true"
       fail-unhealthy: "true"
       fail-unstable: "true"
       health-auto-update: "true"
       stability-auto-update: "true"
       zoom-coverage-chart: "true"
       source-encoding: "Big5"
       targets:
            - files:
                healthy: 10
                unhealthy: 20
                failing: 30
            - method:
                healthy: 50
                unhealthy: 40
                failing: 30
copy-to-master

Copy files to master from slave Requires the Jenkins Copy To Slave Plugin.

Parameters:
  • includes (list) – list of file patterns to copy
  • excludes (list) – list of file patterns to exclude
  • destination (string) – absolute path into which the files will be copied. If left blank they will be copied into the workspace of the current job

Example:

publishers:
  - copy-to-master:
      includes:
        - file1
        - file2*.txt
      excludes:
        - file2bad.txt
coverage

WARNING: The coverage function is deprecated. Instead, use the cobertura function to generate a cobertura coverage report. Requires the Jenkins Cobertura Coverage Plugin.

Example:

publishers:
  - coverage
cppcheck

Cppcheck result publisher Requires the Jenkins Cppcheck Plugin.

Parameters:pattern (str) – file pattern for cppcheck xml report

for more optional parameters see the example

Example:

publishers:
  - cppcheck:
      pattern: "**/cppcheck.xml"
      # the rest is optional
      # build status (new) error count thresholds
      thresholds:
        unstable: 5
        new-unstable: 5
        failure: 7
        new-failure: 3
        # severities which count towards the threshold, default all true
        severity:
          error: true
          warning: true
          information: false
      graph:
        xysize: [500, 200]
        # which errors to display, default only sum
        display:
          sum: false
          error: true
email

Email notifications on build failure.

Parameters:
  • recipients (str) – Recipient email addresses
  • notify-every-unstable-build (bool) – Send an email for every unstable build (default true)
  • send-to-individuals (bool) – Send an email to the individual who broke the build (default false)

Example:

publishers:
  - email:
      recipients: breakage@example.com
email-ext

Extend Jenkin’s built in email notification Requires the Jenkins Email-ext Plugin.

Parameters:
  • recipients (str) – Comma separated list of emails
  • reply-to (str) – Comma separated list of emails that should be in the Reply-To header for this project (default is $DEFAULT_RECIPIENTS)
  • subject (str) – Subject for the email, can include variables like ${BUILD_NUMBER} or even groovy or javascript code
  • body (str) – Content for the body of the email, can include variables like ${BUILD_NUMBER}, but the real magic is using groovy or javascript to hook into the Jenkins API itself
  • attach-build-log (bool) – Include build log in the email (default false)
  • unstable (bool) – Send an email for an unstable result (default false)
  • first-failure (bool) – Send an email for just the first failure (default false)
  • not-built (bool) – Send an email if not built (default false)
  • aborted (bool) – Send an email if the build is aborted (default false)
  • regression (bool) – Send an email if there is a regression (default false)
  • failure (bool) – Send an email if the build fails (default true)
  • improvement (bool) – Send an email if the build improves (default false)
  • still-failing (bool) – Send an email if the build is still failing (default false)
  • success (bool) – Send an email for a successful build (default false)
  • fixed (bool) – Send an email if the build is fixed (default false)
  • still-unstable (bool) – Send an email if the build is still unstable (default false)
  • pre-build (bool) – Send an email before the build (default false)

Example:

publishers:
  - email-ext:
      recipients: foo@example.com, bar@example.com
      reply-to: foo@example.com
      subject: Subject for Build ${BUILD_NUMBER}
      body: The build has finished
      attach-build-log: false
      unstable: true
      first-failure: true
      not-built: true
      aborted: true
      regression: true
      failure: true
      improvement: true
      still-failing: true
      success: true
      fixed: true
      still-unstable: true
      pre-build: true
fingerprint

Fingerprint files to track them across builds

Parameters:
  • files (str) – files to fingerprint, follows the @includes of Ant fileset (default is blank)
  • record-artifacts (bool) – fingerprint all archived artifacts (default false)

Example:

publishers:
  - fingerprint:
      files: builddir/test*.xml
      record-artifacts: false
ftp

Upload files via FTP. Requires the Jenkins Publish over FTP Plugin.

Parameters:
  • site (str) – name of the ftp site
  • target (str) – destination directory
  • target-is-date-format (bool) – whether target is a date format. If true, raw text should be quoted (defaults to False)
  • clean-remote (bool) – should the remote directory be deleted before transfering files (defaults to False)
  • source (str) – source path specifier
  • excludes (str) – excluded file pattern (optional)
  • remove-prefix (str) – prefix to remove from uploaded file paths (optional)
  • fail-on-error (bool) – fail the build if an error occurs (defaults to False).

Example:

publishers:
  - ftp:
      site: 'ftp.example.com'
      target: 'dest/dir'
      source: 'base/source/dir/**'
      remove-prefix: 'base/source/dir'
      excludes: '**/*.excludedfiletype'
groovy-postbuild

Execute a groovy script. Requires the Jenkins Groovy Postbuild Plugin

Parameter :the groovy script to execute

Example:

publishers:
  - groovy-postbuild: "manager.buildFailure()"
jabber

Integrates Jenkins with the Jabber/XMPP instant messaging protocol Requires the Jenkins Jabber Plugin.

Parameters:
  • notify-on-build-start (bool) – Whether to send notifications to channels when a build starts (default false)
  • notify-scm-committers (bool) – Whether to send notifications to the users that are suspected of having broken this build (default false)
  • notify-scm-culprits (bool) – Also send notifications to ‘culprits’ from previous unstable/failed builds (default false)
  • notify-upstream-committers (bool) – Whether to send notifications to upstream committers if no committers were found for a broken build (default false)
  • notify-scm-fixers (bool) – Whether to send notifications to the users that have fixed a broken build (default false)
  • group-targets (list) – List of group targets to notify
  • individual-targets (list) – List of individual targets to notify
  • strategy (dict) –

    When to send notifications (default all)

    strategy values:
     
    • all – Always
    • failure – On any failure
    • failure-fixed – On failure and fixes
    • change – Only on state change
  • message (dict) –

    Channel notification message (default summary-scm)

    message values:
     
    • summary-scm – Summary + SCM changes
    • summary – Just summary
    • summary-build – Summary and build parameters
    • summary-scm-fail – Summary, SCM changes, and failed tests

Example:

publishers:
  - jabber:
      notify-on-build-start: true
      group-targets:
        - "foo-room@conference-2-fooserver.foo.com"
      individual-targets:
        - "foo-user@conference-2-fooserver.foo.com"
      strategy: all
      message: summary-scm
jira

Update relevant JIRA issues Requires the Jenkins JIRA Plugin

Example:

publishers:
  - jira
join-trigger

Trigger a job after all the immediate downstream jobs have completed

Parameters:projects (list) – list of projects to trigger

Example:

publishers:
  - join-trigger:
      projects:
        - project-one
        - project-two
junit

Publish JUnit test results.

Parameters:results (str) – results filename

Example:

publishers:
  - junit:
      results: nosetests.xml
logparser

Requires the Jenkins Log Parser Plugin.

Parameters:
  • parse-rules (str) – full path to parse rules
  • unstable-on-warning (bool) – mark build unstable on warning
  • fail-on-error (bool) – mark build failed on error
Example::
publishers:
  • logparser:

    parse-rules: “/path/to/parserules” unstable-on-warning: true fail-on-error: true

maven-deploy

Deploy artifacts to Maven repository.

Parameters:
  • id (str) – Repository ID
  • url (str) – Repository URL
  • unique-version (bool) – Assign unique versions to snapshots (default true)
  • deploy-unstable (bool) – Deploy even if the build is unstable (default false)

Example:

publishers:
  - maven-deploy:
      id: example
      url: http://repo.example.com/maven2/
      unique-version: true
      deploy-unstable: false
performance

Publish performance test results from jmeter and junit. Requires the Jenkins Performance Plugin.

Parameters:
  • failed-threshold (int) – Specify the error percentage threshold that set the build failed. A negative value means don’t use this threshold (default 0)
  • unstable-threshold (int) – Specify the error percentage threshold that set the build unstable. A negative value means don’t use this threshold (default 0)
  • report (dict) –
    (jmeter or junit):
     (dict or str): Specify a custom report file (optional; jmeter default **/.jtl, junit default */TEST-*.xml)

Examples:

publishers:
  - performance:
      failed-threshold: 85
      unstable-threshold: -1
      report:
         - jmeter: "/special/file.jtl"
         - junit: "/special/file.xml"

publishers:
  - performance:
      failed-threshold: 85
      unstable-threshold: -1
      report:
         - jmeter
         - junit

publishers:
  - performance:
      failed-threshold: 85
      unstable-threshold: -1
      report:
         - jmeter: "/special/file.jtl"
         - junit: "/special/file.xml"
         - jmeter
         - junit
pipeline

Specify a downstream project in a pipeline. Requires the Jenkins Build Pipeline Plugin.

Parameter :the name of the downstream project

Example:

publishers:
  - pipleline: deploy

You can build pipeline jobs that are re-usable in different pipelines by using a Job Template to define the pipeline jobs, and variable substitution to specify the name of the downstream job in the pipeline. Job-specific substitutions are useful here (see Project).

See ‘samples/pipeline.yaml’ for an example pipeline implementation.

scp

Upload files via SCP Requires the Jenkins SCP Plugin.

Parameters:
  • site (str) – name of the scp site
  • target (str) – destination directory
  • source (str) – source path specifier
  • keep-hierarchy (bool) – keep the file hierarchy when uploading (default false)
  • copy-after-failure (bool) – copy files even if the job fails (default false)
  • copy-console (bool) – copy the console log (default false); if specified, omit ‘target’

Example:

publishers:
  - scp:
      site: 'example.com'
      target: 'dest/dir'
      source: 'base/source/dir/**'
sonar

Sonar plugin support. Requires the Jenkins Sonar Plugin.

Parameters:
  • jdk (str) – JDK to use (inherited from the job if omitted). (optional)
  • branch (str) – branch onto which the analysis will be posted (optional)
  • language (str) – source code language (optional)
  • maven-opts (str) – options given to maven (optional)
  • additional-properties (str) – sonar analysis parameters (optional)
  • skip-global-triggers (dict) –
    Triggers:
    • skip-when-scm-change (bool): skip analysis when build triggered by scm
    • skip-when-upstream-build (bool): skip analysis when build triggered by an upstream build
    • skip-when-envvar-defined (str): skip analysis when the specified environment variable is set to true

This publisher supports the post-build action exposed by the Jenkins Sonar Plugin, which is triggering a Sonar Analysis with Maven.

Example:

publishers:
  - sonar:
      jdk: MyJdk
      branch: myBranch
      language: java
      maven-opts: -DskipTests
      additional-properties: -DsonarHostURL=http://example.com/
      skip-global-triggers:
          skip-when-scm-change: true
          skip-when-upstream-build: true
          skip-when-envvar-defined: SKIP_SONAR
ssh

Upload files via SCP. Requires the Jenkins Publish over SSH Plugin.

Parameters:
  • site (str) – name of the ssh site
  • target (str) – destination directory
  • target-is-date-format (bool) – whether target is a date format. If true, raw text should be quoted (defaults to False)
  • clean-remote (bool) – should the remote directory be deleted before transfering files (defaults to False)
  • source (str) – source path specifier
  • excludes (str) – excluded file pattern (optional)
  • remove-prefix (str) – prefix to remove from uploaded file paths (optional)
  • fail-on-error (bool) – fail the build if an error occurs (defaults to False).

Example:

publishers:
  - ssh:
      site: 'server.example.com'
      target: 'dest/dir'
      source: 'base/source/dir/**'
      remove-prefix: 'base/source/dir'
      excludes: '**/*.excludedfiletype'
trigger

Trigger non-parametrised builds of other jobs.

Parameters:
  • project (str) – name of the job to trigger
  • threshold (str) – when to trigger the other job (default ‘SUCCESS’), alternatives: SUCCESS, UNSTABLE, FAILURE

Example:

publishers:
  - trigger:
      project: other_job
trigger-parameterized-builds

Trigger parameterized builds of other jobs. Requires the Jenkins Parameterized Trigger Plugin.

Parameters:
  • project (str) – name of the job to trigger
  • predefined-parameters (str) – parameters to pass to the other job (optional)
  • current-parameters (bool) – Whether to include the parameters passed to the current build to the triggered job (optional)
  • svn-revision (bool) – Pass svn revision to the triggered job (optional)
  • git-revision (bool) – Pass git revision to the other job (optional)
  • condition (str) – when to trigger the other job (default ‘ALWAYS’)
  • property-file (str) – Use properties from file (optional)

Example:

publishers:
  - trigger-parameterized-builds:
      - project: other_job, foo, bar
        predefined-parameters: foo=bar
      - project: other_job1, other_job2
        predefined-parameters: BUILD_NUM=${BUILD_NUMBER}
        property-file: version.prop
      - project: yet_another_job
        predefined-parameters: foo=bar
        git-revision: true
violations

Publish code style violations. Requires the Jenkins Violations Plugin.

The violations component accepts any number of dictionaries keyed by the name of the violations system. The dictionary has the following values:

Parameters:
  • min (int) – sunny threshold
  • max (int) – stormy threshold
  • unstable (int) – unstable threshold
  • pattern (str) – report filename pattern

Any system without a dictionary provided will use default values.

Valid systems are:

checkstyle, codenarc, cpd, cpplint, csslint, findbugs, fxcop, gendarme, jcreport, jslint, pep8, pmd, pylint, simian, stylecop

Example:

publishers:
  - violations:
      pep8:
        min: 0
        max: 1
        unstable: 1
        pattern: '**/pep8.txt'
workspace-cleanup (post-build)

See Workspace Cleanup Plugin.

The pre-build workspace-cleanup is available as a wrapper.

Parameters:
  • include (list) – list of files to be included
  • exclude (list) – list of files to be excluded
  • dirmatch (bool) – Apply pattern to directories too (default: false)
  • clean-if (list) –

    clean depending on build status

    clean-if values:
     
    • success (bool) (default: true)
    • unstable (bool) (default: true)
    • failure (bool) (default: true)
    • aborted (bool) (default: true)
    • not-built (bool) (default: true)
  • fail-build (bool) – Fail the build if the cleanup fails (default: true)
  • clean-parent (bool) – Cleanup matrix parent workspace (default: false)

Example:

publishers:
  - workspace-cleanup:
      include:
        - "*.zip"
      clean-if:
        - success: true
        - not-built: false
xunit

Publish tests results. Requires the Jenkins xUnit Plugin.

Parameters:
  • thresholdmode (str) – whether thresholds represents an absolute number of tests or a percentage. Either ‘number’ or ‘percent’, will default to ‘number’ if omitted.
  • thresholds (dict) – list containing the thresholds for both ‘failed’ and ‘skipped’ tests. Each entry should in turn have a list of “threshold name: values”. The threshold names are ‘unstable’, ‘unstablenew’, ‘failure’, ‘failurenew’. Omitting a value will resort on xUnit default value (should be 0).
  • types (dict) – per framework configuration. The key should be one of the internal types we support: ‘aunit’, ‘boosttest’, ‘checktype’, ‘cpptest’, ‘cppunit’, ‘fpcunit’, ‘junit’, ‘mstest’, ‘nunit’, ‘phpunit’, ‘tusar’, ‘unittest’, ‘valgrind’. The ‘custom’ type is not supported.

Each framework type can be configured using the following parameters:

Parameters:
  • pattern (str) – An Ant pattern to look for Junit result files, relative to the workspace root.
  • requireupdate (bool) – fail the build whenever fresh tests results have not been found (default: true).
  • deleteoutput (bool) – delete temporary JUnit files (default: true)
  • stoponerror (bool) – Fail the build whenever an error occur during a result file processing (default: true).

Example:

publishers:
    - xunit:
        thresholdmode: 'percent'
        thresholds:
          - failed:
                unstable: 0
                unstablenew: 0
                failure: 0
                failurenew: 0
          - skipped:
                unstable: 0
                unstablenew: 0
                failure: 0
                failurenew: 0
        types:
          - phpunit:
              pattern: junit.log
          - cppUnit:
              pattern: cppunit.log

Previous topic

Properties

Next topic

Reporters

This Page