The plugin allows two levels of configuration, each explained in the below sections. The assumption should be that if a project level setting can not be found, the plugin will fall back to the global configuration.
These settings can be found under Manage Jenkins -> Configure System and look for Global HipChat Notifier Settings. The settings listed here are:
- HipChat Server: The hostname (and optionally the port number) for the HipChat server in use. Note that the server will always be accessed via HTTPS. Defaults to api.hipchat.com for cloud installations. The plugin will only connect to the server using TLS protocol, access via SSL protocol is disabled.
- Use v2 API: Whether to use HipChat v2 API when interacting with the HipChat server. Note: that support for v1 version of the API is going to be removed in the next major version.
- Credentials: The 'secret text' kind of credential to be used when accessing HipChat REST endpoints. When using v2 API, the Credentials must be a valid OAuth2 token obtained as described in the v2 API documentation. When v2 API is disabled, the plugin will use v1 API to perform its operations. The v1 API requires API Tokens (which are different from OAuth2 tokens!).
- Room: Allows to specify the name or ID of the room where the notification(s) should be sent. If the name of the room is not known at the time of the configuration, you can also use build variables (e.g. $HIPCHAT_ROOM). Multiple values can be provided, in which case use comma to separate the values.
- Send As: When using the v1 API the value defined here will be used as the sender for the notification. The value must be less than 15 characters long.
- Card Provider: Here you can select a card provider implementation which is responsible to render a HipChat Card as needed. See below for more information on custom Card providers. Cards are only supported when v2 version of the HipChat API is in use.
- Default notifications: Configure the default set of notifications. These will be used when there is no notification configured at the job level. Note that the default notifications are only sent if the HipChat Notifications Post Build Action is added to the job (otherwise the plugin won't get invoked).
Job level configuration
To set up the plugin for an individual job, go to the job's configuration page and add the HipChat Notifications post-build action. The settings listed there are:
- Credentials: Use in case you have a room-specific token to override the globally set Credentials.
- Project Room: Allows to specify the name or ID of the room where the notification(s) should be sent. If the name of the room is not known at the time of the configuration, you can also use build variables (e.g. $HIPCHAT_ROOM). Multiple values can be provided, in which case use comma to separate the values.
- Notifications: The list of notifications that should be sent out upon build events. If this setting is left empty, the plugin will fall back to the Default notifications setting in the Global configuration. The settings available for each notification entry:
- Notify Room: Whether the message should trigger a HipChat notification
- Text Format: When checked, the message will be sent in text format, instead of the default HTML format. When using text format emoticons will display in messages, but links must be printed in full length.
- Notification Type: Select which build status/result should trigger this notification.
- Color: Select the color of the notification message.
- Message template: The specific message template to use for this notification
- Message templates: These templates are used as default values when the notification-specific message template is not defined.
- Job started: The message to use when the build starts.
- Job completed: The message to use when the build completes regardless of the build result.
- authenticated proxies
- “No Proxy Host” setting
When using pipeline projects, HipChat messages can be sent using the following DSL:
Support for custom Card Providers
HipChat supports various kinds of cards for its notifications, as such the card implementation in the Jenkins HipChat plugin has been done in a pluggable manner. In case the out of the box available card implementations do not fit your needs, the following extension will need to be written:
- Plugin fails with NPE if changeset cannot be computed (#89)
- Very long notification messages caused HTTP 400 errors (#87)
- Need ability to turn off blue ocean URLs (#92) -> $BLUE_OCEAN_URL has been introduced to represent these URLs instead. $URL/$BUILD_URL now always results in classic UI links
- BUILD_DURATION token renders "and counting" messages in pipeline jobs (JENKINS-40461)
Version 2.0.0 (Oct 27, 2016)
The plugin now requires JDK 7 runtime.