search

jenkinsci / jms-messaging-plugin

https://plugins.jenkins.io/jms-messaging
12 stars 37 forks source link

readme

Build Status Contributors Jenkins Plugin GitHub release Jenkins Plugin Installs

JMS Messaging Plugin

JMS Messaging Providers

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

Set Up

Global Configuration

Before the plugin may be used, you must add a JMS Messaging Provider. This will provide the ability to send and receive messages. Below is a list of currently supported JMS Message Providers:

Configuration as code

Example:

unclassified:
  jmsProviders:
    configs:
      - fedMsg:
          name: "Fedora messages"
          hubAddr: "tcp://example.com:5678"
          pubAddr: "tcp://example.com:6789"
          topic: "org.fedora.bar"
      - activeMq:
          name: "Active MQ"
          broker: "foo.com:4242"
          topic: "active.mq.com"
          topicProvider: "default"
          useQueues: false
          authenticationMethod:
            simple:
              username: "foo"
              password: "bar" # User, encrypt secrets
      - rabbitMq:
          name: "Rabbit MQ"
          exchange: "ex"
          hostname: "rabbitmq.example.com"
          portNumber: "4545"
          queue: "foo.bar"
          topic: "baz"
          virtualHost: "rabbitvh.example.com"
          authenticationMethod:
            sslCertificate:
              keystore: "/tmp/key"
              keypwd: "keypwd" # User, encrypt secrets
              truststore: "/tmp/trust"
              trustpwd: "trustpwd" # User, encrypt secrets

Triggering

To enable the CI trigger, go to the job configuration page and add click the check box "CI Event" under the Build Triggers section. Enabling the trigger on a job requires two additional pieces of information:

The complete documentation for JMS selectors can be found here: http://activemq.apache.org/selectors.html

Message Types

In the image above, the selector contains CI_TYPE = '\<message-type>'

The valid values for '\<message-type>' can be found in the "Type" column in the table below:

Message Description Type
Code quality checks done Indicate that static analysis covering code quality is complete. code-quality-checks-done
Component build done Indicate that a component has been built. component-build-done
Component functional test coverage done Indicate that test coverage for component tests is complete. functional-test-coverage-done
Custom Indicate a custom event not covered by the other message types. custom
Early performance testing done Indicate that early automated performance testing is complete. early-performance-testing-done
Early security testing done Indicate that early automated security testing is complete. early-security-testing-done
Engineering product build accepted for release testing Indicate that engineering product build has been accepted as a release candidate. product-accepted-for-release-testing
Engineering product build in staging environment Indicate that engineering product build has been pushed to staging environment. product-build-in-staging
Functional testing done Indicate that all planned functional testing is complete. functional-testing-done
Image Uploaded Indicate that a cloud image has been uploaded image-uploaded
Nonfunctional testing done Indicate that all planned nonfunctional testing is complete. nonfunctional-testing-done
Out of the box testing done Indicate that end user testing is complete. ootb-testing-done
Peer review done Indicate that development has completed peer review of the code change. peer-review-done
Product build done Indicate that a new product build is complete. product-build-done
Product test coverage done Indicate that test coverage for functional product tests is complete. product-test-coverage-done
Pull request submitted Indicate that a code change needs to be reviewed and tested. pull-request
Security checks done Indicate that static analysis covering security issues is complete. security-checks-done
Tier 0 testing done Indicate that tier 0 (unit) testing has completed. tier-0-testing-done
Tier 1 testing done Indicate that tier 1 (component) testing is complete. tier-1-testing-done
Tier 2 build validation done Indicate that the build validation is complete. tier-2-validation-testing-done
Tier 2 integration testing done Indicate that tier 2 (functional product) automated testing is complete. tier-2-integration-testing-done
Tier 3 testing done Indicate that tier 3 testing is complete. tier-3-testing-done
Unit test coverage done Indicate that test coverage for unit tests is complete. unit-test-coverage-done
Update defect status Indicate a code change to resolve a defect has been reviewed and tested and the defect status needs to be updated. update-defect-status

Build Steps

CI Notifier

This plugin provides a build step for publishing messages to the topic upon job completion. To add the CI Notifier build step, go to the job configuration page and select the "CI Notifier" option.

Adding the step to the job requires some additional information:

The full list of message types available in the drop-down menu can be found in the Message Type table above.

CI Subscriber

This plugin provides a build step to wait for a specific message. To add the CI Subscriber build step, go to the job configuration page and select the "CI Subscriber" option.

Adding the step to the job requires some additional information:

The build step will set an environment variable with the name from Variable with a value of the message content.

Post-build steps

CI Notifier

See above.

Pipeline Support

Triggers

The CI trigger is available via the triggers section in a declarative pipeline:

triggers {
    ciBuildTrigger(noSquash: false,
        providerList: [ activeMQSubscriber(name: 'Red Hat UMB',
                        checks: [
                            [
                                expectedValue: '^foo.*bar$',
                                field: '$.msg.tag'
                            ]
                        ],
                        overrides: [topic: 'Consumer.rh-jenkins-ci-plugin.8dad9900-abcabc.VirtualTopic.eng.ci.example.durable.test.abcabc'] )
        ]
    )
}

Job DSL Support

Here is a usage example for Job DSL:

ciBuildTrigger {
    providers {
      providerDataEnvelope {
        providerData {
          activeMQSubscriber {
            name("Red Hat UMB")
            overrides {
              def uuid = "4ba46bbc-949b-11e8-b83f-54ee754ea14c"
              topic("Consumer.rh-jenkins-ci-plugin.${uuid}.VirtualTopic.eng.ci.redhat-container-image.pipeline.running")
            }
            // Message Checks
            checks {
              msgCheck {
                field('$.artifact.type')
                expectedValue("cvp")
              }
            }
          }
        }
      }
    }
    noSquash(true)
  }
}

Steps

This plugin provides the steps when using the Jenkins Pipeline feature:

Here are some examples:

node('master') {
   // Send a message that CodeQualityChecksDone
    def sendResult = sendCIMessage \
        providerName: 'default', \
        messageContent: 'some content', \
        messageProperties: 'CI_STATUS = passed', \
        messageType: 'CodeQualityChecksDone'
    // echo sent message id and content
    echo sendResult.getMessageId()
    echo sendResult.getMessageContent()
}

and

node('master') {
    // Wait for message and store message content in variable
    def msgContent = waitForCIMessage \
         providerName: 'default', \
         selector: "CI_TYPE = 'code-quality-checks-done' and CI_STATUS = 'passed'"
    echo "msgContent = " + msgContent
}

Change Log

Version 1.1.18 (April 23, 2020)

Version 1.1.17 (April 19, 2020)

Version 1.1.16 (April 9, 2020)

WARNING: This version contains a regression involving the display of job configuration data of Pipeline jobs. Please use v1.1.17

Version 1.1.15 (March 19, 2020)

Version 1.1.14 (March 12, 2020)

Version 1.1.13 (Feb 20, 2020)

Version 1.1.12 (January 8, 2020)

Version 1.1.11 (November 6, 2019)

Version 1.1.10 (November 6, 2019)

Version 1.1.9 (July 16, 2019) 

Version 1.1.8 (June 5, 2019) 

Version 1.1.7 (May 21, 2019) 

Version 1.1.6 (Mar 05, 2019) 

Version 1.1.5 (Feb 27, 2019) 

Version 1.1.4 (Feb 21, 2019) 

Version 1.1.3 (Feb 15, 2019) 

Version 1.1.2 (Feb 11, 2019) 

Version 1.1.1 (June 20, 2018) 

Version 1.1.0 (June 12, 2018) 

Version 1.0.40 (May 25, 2018)

Version 1.0.39 (May 17, 2018) 

Breaking change

WARNING: Version 1.0.39 no longer supports a JMS selector for the FedMsg Messaging Provider. You must update your jobs to add a Message Check to specify what you want to trigger on.

Version 1.0.38

Version 1.0.37

Version 1.0.36

Version 1.0.35

Version 1.0.34

Version 1.0.32

Version 1.0.31

Version 1.0.30

Version 1.0.29

Version 1.0.28

Version 1.0.27

Version 1.0.26

Version 1.0.25

Version 1.0.24

Version 1.0.23

Version 1.0.22

Version 1.0.21

Version 1.0.20

Version 1.0.19

Version 1.0.18

Version 1.0.17

Version 1.0.16

Version 1.0.15

Version 1.0.14

Version 1.0.13

Version 1.0.12

Version 1.0.11

Version 1.0.10

Version 1.0.9

Version 1.0.8

Version 1.0.7

Version 1.0.6

Version 1.0.5

Version 1.0.4

Version 1.0.3

Version 1.0.2

Version 1.0.1

Version 1.0.0