Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3
Wiki Markup
{jenkins-plugin-info:pluginId=hipchat}

Configuration

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.

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 RoomAllows 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.

Message template format

The message templates used by the plugin now fully support token-macro tokens, for a comprehensive list of the available tokens, please check out the help texts for the message template settings.

In addition to the out of the box supported tokens from the token-macro-plugin, the plugin can also utilize various other tokens provided by other plugins. Having the email-ext-plugin installed on Jenkins will make the following (non-comprehensive list of) tokens available for example:

  • TRIGGER_NAME
  • TEST_COUNTS
  • FAILED_TESTS

If you find that one of the above listed tokens do not work with the plugin, you should probably check first whether the email-ext-plugin is installed on your Jenkins instance. The same rule applies for other third party token provider plugins.

The HipChat plugin also provides the following token implementations:

Token name

Content

Example value

BLUE_OCEAN_URL

Blue Ocean UI friendly link to the currently built job

http://localhost:8080/jenkins/job/foobar/1/display/redirect

BUILD_DURATION

The duration of the build in human readable format

42 min

COMMIT_MESSAGE

The first line of the last changeset’s commit message

Initial commit

HIPCHAT_CHANGES

Human readable details of the new changesets or “No changes” if changesets weren’t computed for this build

Started by changes from bjensen (1 file(s) changed)

HIPCHAT_CHANGES_OR_CAUSE

Returns HIPCHAT_CHANGES if it was successfully calculated, otherwise returns the cause of the build

Started by user Admin

TEST_REPORT_URL

Direct link to the test reports

http://localhost:8080/jenkins/job/foobar/1/testReport

Proxy support

The plugin utilizes the proxy configuration in Jenkins when making external HTTPS connections. To configure proxy in Jenkins, follow the Jenkins documentation.

The currently supported features are:

  • authenticated proxies
  • “No Proxy Host” setting

Pipeline support

When using pipeline projects, HipChat messages can be sent using the following DSL:

Code Block
hipchatSend color: 'YELLOW', credentialId: 'myid', failOnError: true, message: 'test', notify: true, room: 'Jenkins', sendAs: 'Jenkins', server: 'api.hipchat.com', textFormat: true, v2enabled: true

Note that the following parameters for the hipchatSend step are planned to be deprecated in the next major version:

  • sendAs
  • server
  • token
  • v2enabled

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:

Code Block
@Extension
public class MyCoolCardProvider extends CardProvider {

    private static final Logger LOGGER = Logger.getLogger(MyCoolCardProvider.class.getName());

    @Override
    public Card getCard(Run<?, ?> run, TaskListener taskListener, String message) {
        // implement magic
    }

    @Override
    public CardProviderDescriptor getDescriptor() {
        return new DescriptorImpl();
    }

    @Extension
    public static class DescriptorImpl extends CardProviderDescriptor {

        @Override
        public String getDisplayName() {
            return "My cool card provider";
        }
    }
}

The return value type Card represents a HipChat card and exposes all of its available properties as it is defined in the HipChat API documentation.
The idea behind the extensible approach is that lots of different card implementations can be made available. If you do end up writing a custom CardProvider, please open a pull request, so that others can benefit from it too. Having these custom implementations contributed should also ensure (to a reasonable degree) that future API changes will be reflected on these implementations as the changes are being made.

Changelog

Version 2.1.1 (Feb 15, 2017)

Bugfixes:

  • BUILD_DURATION in pipeline builds always displayed "0 ms" (JENKINS-41861)
  • The HipChat cards should use HTTPS to display the Jenkins logo (#94) - Note: the cards only work when v2 API is enabled.
  • HIPCHAT_CHANGES_OR_CAUSE and COMMIT_MESSAGE variables weren't working at all in pipeline builds (JENKINS-41861)

Version 2.1.0 (Feb 7, 2017)

Note
  • The $PRINT_FULL_ENV variable is no longer supported.
  • Several tokens that were possible to use in previous versions, are now deprecated and eventually will not be supported. To remain backwards compatible, the plugin still supports all the old tokens, but their replacement to the new tokens are recommended

    Deprecated token

    Supported replacement

    $DURATION

    $BUILD_DURATION

    $JOB_DISPLAY_NAME

    $PROJECT_DISPLAY_NAME

    $TEST_COUNT

    ${TEST_COUNTS,var=\"total\"}

    $FAILED_TEST_COUNT

    ${TEST_COUNTS,var=\"fail\"}

    $SKIPPED_TEST_COUNT

    ${TEST_COUNTS,var=\"skip\"}

    $SUCCESS_TEST_COUNT

    ${TEST_COUNTS,var=\"pass\"}

    $URL

    $BUILD_URL

    $COMMIT_MESSAGE_TEXT

    ${COMMIT_MESSAGE,escape=false}

    $CHANGES

    $HIPCHAT_CHANGES

    $CHANGES_OR_CAUSE

    $HIPCHAT_CHANGES_OR_CAUSE

New Features:

  • Support for HipChat cards (#85, JENKINS-32083)
  • Support for token-macro-plugin tokens (#59, #65, #88, #90, JENKINS-34934)

Bugfixes:

  • 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)

Note

The plugin now requires JDK 7 runtime.

New Features:

  • Blue Ocean UI support - the HipChat plugin should now generate URLs that are compatible with Blue Ocean (#82)
  • Expose commit message as a variable, $COMMIT_MESSAGE (when using HTML format) and $COMMIT_MESSAGE_TEXT (when using text format) variables have been added
  • Display "No changes" if no SCM change happened between builds
  • v1/v2 API/OAuth2 tokens are now stored in Jenkins using the Credential API. Existing keys will be migrated across to the new format as part of Jenkins upgrade (JENKINS-27303)
  • Expose $SUCCESS_TEST_COUNT and $SKIPPED_TEST_COUNT as message template variables

Bugfixes:

  • Fix incorrect link for help text (#76)
  • Small updates to logging statement to make the plugin a bit less verbose
  • Made the help text for message templates more available, should be harder to miss the available variables
  • Plugin ignored proxy authentication settings (JENKINS-33214)

Version 1.1.0 (Oct 27, 2016)

Warning

The release build was terminated half-way in the process due to a socket timeout. Usage of 1.1.0 version is NOT recommended.

Version 1.0.0 (Jan 9, 2016)

Note

The plugin now requires at least Jenkins 1.609.2.

New Features:

  • Flexible notification configuration:
    • allow setting room notification, message template and notification color for each notification type (JENKINS-18127, JENKINS-28314, JENKINS-26974, #16, #54)
    • introduce default notifications (can be set under Global settings), which are only triggered if a job has no notifications set up (#30)
    • configuration stored in old format will keep on working
  • Expose failed and total test count in message templates, use $FAILED_TEST_COUNT and $TEST_COUNT respectively (#18)
  • Workflow plugin support (#60, JENKINS-27202)
  • Text format support (#47)

Bugfixes:

  • Potential NPE when collecting changeset information from git repositories (#55)

Version 0.2.0 (Sept 14, 2015)

Bugfixes:

  • Fix help message for v2 setting (#41, JENKINS-27304)
  • space in room name resulted in failure with v2 API (#52)
  • ABORTED->SUCCESS didn't result in a BACK_TO_NORMAL notification (#51)
  • noProxyHost setting is not obeyed (JENKINS-29057)

New Features:

  • Improve error handling, output messages to build logs (#9)
  • Room name now can be parameterized (#44, JENKINS-22723)
  • Added extra validation for the "Send As" field with helpful error messages (#46)
  • Improved support for matrix builds, now it's possible to select how and when should the plugin send notifications for Matrix builds (#50)
  • JOB_DISPLAY_NAME macro is now available, should contain the project's display name similarly to pre 0.1.9 notifications (JENKINS-27712)
  • Explicitly enable TLSv* protocols for the outgoing SSL connections (#49)

Version 0.1.9 (Mar 9, 2015)

Bugfixes:

  • Room setting and notification selection should be per post-build task, not per build (#29, JENKINS-25908)
  • Job configuration won't get updated when global configuration changes (#31, #33, JENKINS-19184, JENKINS-26845)
  • No HipChat notification sent when build status change from "Unstable" to "Back To Normal" (JENKINS-25714)
  • The plugin should set HTTP connect/read timeouts (#22)
  • Incorrect path to help files for config pages (#35)

New Features:

  • Support for HipChat v2 & per-project auth token settings (#11)
  • Allow customization of notification messages (#25)
  • Use full project display name in notifications (#12)
  • Introduce a Test Configuration button on global config page (#24)
  • The configuration pages are now localizable