{% extends "zephyr/portico.html" %} {# API information page #} {% block portico_content %}

Integrations

The English poet John Donne once wrote that "no man is an island", and we feel the same about software. No system exists in complete isolation, so we've made it easy for Humbug to connect to the services you already use.

With the integrations below, your team can stay up-to-date on code changes, issue tickets, build system results, and much more. So ask not for whom the notification tolls—it tolls for thee! (Or for a team member of yours, I guess.)

Getting started

Many of these integrations are available in our API download. They also require a registered Humbug user to send as. You can use your existing account, or register a new one for them. (If new email addresses are hard to come by, you can use something like wdaher+github@example.com.)

Services with integrations

{#--------------------------------------------------------------------#}

Beanstalk

Humbug supports both SVN and Git notifications from Beanstalk. In the beanstalk web application, go to the Setup page, and choose the Integrations tab. Choose the Webhooks integration from the list presented. Make sure to replace the @ in your email address with %40, as Beanstalk's website will incorrectly refuse to parse a username containing a @.

In the URL field, enter https://email:api_key@humbughq.com/api/v1/external/beanstalk:

Congratulations! You're done!
Whenever you do a deployment, you'll get an automated notification that looks like this:

^ Back to top

{#--------------------------------------------------------------------#}

Capistrano

First, download and install our Python bindings and example scripts on your Capistrano server. Once you've done that, you'll use the humbug-send utility to notify you when certain events happen.

Here's some example code for sending a Humbug notification after a deployment has completed:

after 'deploy', 'notify:humbug'

namespace :notify do
  desc "Post a message to Humbug that we've deployed"
  task :humbug do
    # this will post to Humbug as the user defined in ~/.humbugrc
    run_locally "echo ':beers: I just deployed to #{stage}! :beers:' | humbug-send --stream commits --subject deployments || true"
  end
end

Some notes:

  • Make sure you've created a filled-out ~/.humbugrc on your Capistrano machine.
  • You may need to change the deploy above to another step of your deployment process, if you'd like the notification to fire at a different time.

Congratulations! You're done!
Whenever you do a deployment, you'll get an automated notification that looks like this:

Thanks to Wes of TurboVote for submitting this integration!

^ Back to top

{#--------------------------------------------------------------------#}

Git

First, download and install our Python bindings and example scripts on your Git server.

Next, open integrations/git/humbug_git_config.py in your favorite editor, and change the following lines to specify the email address and API key for your Git bot:

HUMBUG_USER = "git@example.com"
HUMBUG_API_KEY = "0123456789abcdef0123456789abcdef"

You can also specify which pushes will result in notifications and to what stream the notifications will be sent by modifying the commit_notice_destination function in humbug_git_config.py. By default, pushes to the master and test-post-receive branches will result in a notification to stream commits.

Save integrations/git/humbug_git_config.py to the .git/hooks directory of your git repository.

Symlink /usr/local/share/humbug/integrations/git/post-receive into the .git/hooks directory of your git repository.

Congratulations! You're done!
Whenever you make a push to the master branch of your git repository (or whatever you configured above), the Humbug git plugin will send an automated notification that looks like this:

Testing
You can test the plugin without changing your master branch by pushing to the test-post-receive branch.

^ Back to top

{#--------------------------------------------------------------------#}

GitHub

First, go to your repository page and click "Settings":

From there, select "Service Hooks":

Select "Humbug" from the list, fill in the API key and email address for your bot, check the "active" checkbox, and pick "Update settings":

Congratulations! You're done!
When people push to your repository, you'll see a commit message like the following, to the stream commits with a subject that matches the repository name (in this case "humbug-test"):

^ Back to top

{#--------------------------------------------------------------------#}

Jenkins (or Hudson)

Install the "Humbug" plugin by going to Manage Jenkins > Manage Plugins > Available, typing in "Humbug", and clicking "Install without restart".

Once the plugin is installed, configure it by going to Manage Jenkins > Configure System.

Scroll to the section labeled "Humbug Notification Settings", and specify your bot's email address, API key, and where you'd like your notification messages to go (we recommend the stream jenkins).

The other two options you might want to adjust are "Smart Notification" (do you want a message after every single build, or only after a status change?), and "Jenkins URL"—the URL to your instance of Jenkins, so that we can link you to specific build reports.

Once you've done that, it's time to configure one of your projects to use the Humbug notification plugin. From your project page, click "Configure" on the left sidebar:

Then, scroll to the bottom until you find the section labeled "Post-build Actions". Click the dropdown and select "Humbug Notification". It should look as below. Then click "Save".

Congratulations! You're done!
When your builds fail or succeed, you'll see a commit message like the following with a subject that matches the project name (in this case "Humbug Test"):

Troubleshooting

If you don't see the Humbug option in the list, confirm that the plugin was successfully installed by going to Manage Jenkins > Manage Plugins > Installed and confirming that "Humbug Plugin" appears in the list. If it does not, the plugin was not successfully installed. Make sure that you have the Maven plugin installed and try again, or email support@humbughq.com for help.

^ Back to top

{#--------------------------------------------------------------------#}

JIRA

Webhook mechanism
If you are running JIRA version 5.2 or greater, or are using the hosted JIRA provided by Atlassian, you can use the built in web-hook support to connect to Humbug. If you are not using the Atlassian-hosted JIRA, you may also use the Jira Plugin mechanism that supports older versions of JIRA.

In your JIRA administration control panel, go to the Webhooks page. If you are using the OnDemand hosted JIRA, follow the instructions on the Atlassian wiki for locating the Webhook UI.

Give your new web hook a name, and for the URL provide https://humbughq.com/api/v1/external/jira/API_KEY where API_KEY is the api key of the user you wish to post JIRA updates as.

Congratulations! You're done!
Updates from JIRA will be sent to the jira stream, and it must already exist.

^ Back to top

{#--------------------------------------------------------------------#}

JIRA

Plugin mechanism
First, download and install our Python bindings and example scripts.

Plugin Installation

The JIRA integration plugin requires two JIRA plugins. Please install the following plugins using the Universal Plugin Manager in your JIRA installation:

SSL Setup

As Humbug is using a StartCOM SSL certificate that is not recognized by default in the Java installation shipped with JIRA, you will need to tell JIRA about the certificate. Navigate to Administration > System > Configure SSL and in the Import SSL Certificates field, enter https://www.humbughq.com. After clicking Save Certificates, follow the on-screen instructions and restart JIRA for it to recognize the proper certificates.

Humbug Integration

Copy the folder integrations/jira/org/ (from the tarball you downloaded above) to your JIRA classes folder. For self-contained JIRA installations, this will be atlassian-jira/WEB-INF/classes/, but this may be different in your deployment.

Edit the constants at the top of org/humbug/jira/HumbugListener.groovy and fill them with the appropriate values: 
String humbugEmail = "jira-notifications@example.com"
String humbugAPIKey = "0123456789abcdef0123456789abcdef"
String humbugStream = "JIRA"
String issueBaseUrl = "https://jira.COMPANY.com/browse/"

In the Administrators page, navigate to Plugins > Other > Script Listeners. In the Add Listener section, click on the Custom Listener option. Select the events you wish the Humbug integration to fire for, and the projects you wish Humbug to be notified for. In the Name of groovy class field, enter org.humbug.jira.HumbugListener.

Click Add Listener, and JIRA will now notify your Humbug of changes to your issues!

Congratulations! You're done!
Updates from JIRA will be sent to the stream you've configured, as below.

^ Back to top

{#--------------------------------------------------------------------#}

Nagios

First, download and install our Python bindings and example scripts on your Nagios server.

Next, open integrations/nagios/humbugrc.example in your favorite editor, and change the following lines to specify the email address and API key for your Nagios bot, saving it to /etc/nagios3/humbugrc on your Nagios server:

[api]
email=NAGIOS_EMAIL_ADDRESS
key=NAGIOS_API_KEY

Copy integrations/nagios/humbug_nagios.cfg to /etc/nagios3/conf.d on your Nagios server.

Finally, add humbug to the members list for one or more of the contact groups in the CONTACT GROUPS section of /etc/nagios3/conf.d/contacts.cfg, doing something like: 

define contactgroup{
        contactgroup_name       admins
        alias                   Nagios Administrators
        members                 monitoring, humbug
        }
Once you've done that, reload your Nagios configuration using /etc/init.d/nagios3 reload.

Congratulations! You're done!
When your Nagios system makes an alert, you'll see a message like the following, to the stream nagios (to change this, edit the arguments to nagios-notify-humbug in /etc/nagios3/conf.d/humbug_nagios.cfg) with a subject indicating the service with an issue:

Testing
If you have external commands enabled in Nagios, you can generate a test notice from your Nagios instance by visiting using the Send custom service notification command in the Service Commands section of any individual service's page on your Nagios instance.

Troubleshooting
You can confirm whether you've correctly configured Nagios to run the Humbug plugin by looking for SERVICE NOTIFICATION lines mentioning humbug in /var/log/nagios3/nagios.log. You can confirm whether you've configured the Humbug plugin code correctly by running /usr/local/share/humbug/integrations/nagios/nagios-notify-humbug directly.

^ Back to top

{#--------------------------------------------------------------------#}

Trac

First, download and install our Python bindings and example scripts on your Trac server.

Next, open integrations/trac/humbug_trac_config.py in your favorite editor, and change the following lines to specify your bot's email address, API key, and where you'd like your notification messages to go (by default, stream trac):

HUMBUG_USER = "trac-notifications@example.com"
HUMBUG_API_KEY = "0123456789abcdef0123456789abcdef"
STREAM_FOR_NOTIFICATIONS = "trac"
TRAC_BASE_TICKET_URL = "https://trac.example.com/ticket"

Copy integrations/trac/humbug_trac.py and integrations/trac/humbug_trac_config.py into your Trac installation's plugins/ subdirectory. Once you've done that, edit your Trac installation's conf/trac.ini to add humbug_trac to the [components] section, as follows:

[components]
humbug_trac = enabled

You may then need to restart Trac (or Apache) so that Trac will load our plugin.

Congratulations! You're done!
When people open new tickets (or edit existing tickets), you'll see a message like the following, to the stream trac (or whatever you configured above) with a subject that matches the ticket name:

Additional trac configuration
After using the plugin for a while, you may want to customize which changes to tickets result in a Humbug notification using the TRAC_NOTIFY_FIELDS setting in humbug_trac_config.py.

^ Back to top

{% endblock %} {% block customhead %} {{ block.super }} {% endblock %}