2013-02-06 20:25:04 +01:00
{% extends "zephyr/portico.html" %}
{# API information page #}
{% block portico_content %}
< div class = "row-fluid" >
< div class = "span8" >
< h2 > Integrations< / h2 >
2013-02-07 00:26:51 +01:00
< p > 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.< / p >
< p > 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.)< / p >
2013-02-06 20:25:04 +01:00
< h3 > Getting started< / h3 >
< p > Many of these integrations are available in
our < a href = "/api" > API download< / a > . They also require a
registered Humbug user to send as. You can use your existing
2013-02-06 23:12:25 +01:00
account, or
2013-03-07 23:05:31 +01:00
< a href = "{% url 'zephyr.views.accounts_home' %}" > register< / a > a new
2013-02-06 23:12:25 +01:00
one for them. (If new email addresses are hard to come by, you can
use something like < code > wdaher+github@example.com< / code > .)< / p >
2013-02-06 20:25:04 +01:00
< h3 id = "services" > Services with integrations< / h3 >
< ul >
2013-04-01 23:57:42 +02:00
< li > < a href = "#beanstalk" > Beanstalk< / a > < / li >
2013-03-19 21:22:50 +01:00
< li > < a href = "#capistrano" > Capistrano< / a > < / li >
2013-02-06 20:25:04 +01:00
< li > < a href = "#git" > Git< / a > < / li >
< li > < a href = "#github" > GitHub< / a > < / li >
2013-02-10 00:35:06 +01:00
< li > < a href = "#jenkins" > Jenkins (or Hudson)< / a > < / li >
2013-03-29 22:57:10 +01:00
< li > < a href = "#jira" > Jira (hosted or v5.2+)< / a > < / li >
< li > < a href = "#jira-plugin" > Jira (locally installed)< / a > < / li >
2013-02-06 20:25:04 +01:00
< li > < a href = "#nagios" > Nagios< / a > < / li >
2013-02-13 22:19:08 +01:00
{% comment %}
2013-02-06 20:25:04 +01:00
< li > < a href = "#pivotal" > Pivotal Tracker< / a > < / li >
< li > < a href = "#svn" > Subversion< / a > < / li >
2013-02-06 22:31:26 +01:00
{% endcomment %}
2013-02-06 20:25:04 +01:00
< li > < a href = "#trac" > Trac< / a > < / li >
2013-02-06 22:31:26 +01:00
{% comment %}
2013-02-06 20:25:04 +01:00
< li > < a href = "#trello" > Trello< / a > < / li >
< li > < a href = "#twitter" > Twitter< / a > < / li >
{% endcomment %}
< li > ...and more coming soon! < a href = "mailto:support@humbughq.com?subject=Integration+request" > Email us< / a > with requests!< / li >
< / ul >
2013-04-01 23:57:42 +02:00
{#--------------------------------------------------------------------#}
< div id = "beanstalk" class = "integration" >
< h4 > Beanstalk< / h4 >
< p > Humbug supports both SVN and Git notifications from Beanstalk. In the beanstalk web application, go to the Setup page, and choose the Integrations tab.
2013-04-02 23:31:48 +02:00
Choose the < code > Webhooks< / code > integration from the list presented. Make sure to replace the < code > @< / code > in your email address with < code > %40< / code > ,
as Beanstalk's website will incorrectly refuse to parse a username containing a < code > @< / code > .< / p >
2013-04-01 23:57:42 +02:00
< p > In the URL field, enter < code > https://email:api_key@humbughq.com/api/v1/external/beanstalk< / code > :< / p >
< img class = "screenshot" src = "/static/images/integrations/beanstalk/001.png" >
< p > < b > Congratulations! You're done!< / b > < br / > Whenever you do a
deployment, you'll get an automated notification that looks like
this:< / p >
< img class = "screenshot" src = "/static/images/integrations/beanstalk/002.png" >
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-03-19 21:22:50 +01:00
{#--------------------------------------------------------------------#}
< div id = "capistrano" class = "integration" >
< h4 > Capistrano< / h4 >
< p > First, download and install our < a href = "/api" > Python
bindings and example scripts< / a > on your Capistrano server.
Once you've done that, you'll use the < code > humbug-send< / code >
utility to notify you when certain events happen.< / p >
< p > Here's some example code for sending a Humbug notification
after a deployment has completed:< / p >
2013-03-26 18:12:00 +01:00
< div class = "codehilite" > < pre > < span class = "n" > after< / span > < span class = "s1" > 'deploy'< / span > < span class = "p" > ,< / span > < span class = "s1" > 'notify:humbug'< / span >
2013-03-19 21:22:50 +01:00
< span class = "n" > namespace< / span > < span class = "ss" > :notify< / span > < span class = "k" > do< / span >
< span class = "n" > desc< / span > < span class = "s2" > "Post a message to Humbug that we've deployed"< / span >
< span class = "n" > task< / span > < span class = "ss" > :humbug< / span > < span class = "k" > do< / span >
< span class = "c1" > # this will post to Humbug as the user defined in ~/.humbugrc< / span >
< span class = "n" > run_locally< / span > < span class = "s2" > "echo ':beers: I just deployed to < / span > < span class = "si" > #{< / span > < span class = "n" > stage< / span > < span class = "si" > }< / span > < span class = "s2" > ! :beers:' | humbug-send --stream commits --subject deployments || true"< / span >
< span class = "k" > end< / span >
< span class = "k" > end< / span >
< / pre > < / div >
< p > Some notes:< / p >
< ul >
< li > Make sure you've created a
filled-out < code > ~/.humbugrc< / code > on your Capistrano
machine.< / li >
2013-03-26 18:12:00 +01:00
< li > You may need to change the < code > deploy< / code > above to
another step of your deployment process, if you'd like the
notification to fire at a different time.< / li >
2013-03-19 21:22:50 +01:00
< / ul >
< em > < / em > < / p >
< p > < b > Congratulations! You're done!< / b > < br / > Whenever you do a
deployment, you'll get an automated notification that looks like
this:< / p >
< img class = "screenshot" src = "/static/images/integrations/capistrano/001.png" >
< p > < small > Thanks to Wes of TurboVote for < a href = "https://gist.github.com/cap10morgan/5100822" > submitting this integration< / a > !< / small > < / p >
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-02-15 23:01:55 +01:00
{#--------------------------------------------------------------------#}
< div id = "git" class = "integration" >
< h4 > Git< / h4 >
< p > First, download and install our < a href = "/api" > Python
bindings and example scripts< / a > on your Git server.< / p >
< p > Next, open < code > integrations/git/humbug_git_config.py< / code >
in your favorite editor, and change the following lines to
specify the email address and API key for your Git bot:< / p >
< div class = "codehilite" > < pre > < span class = "n" > HUMBUG_USER< / span > < span class = "o" > =< / span > < span class = "s" > "git@example.com"< / span >
< span class = "n" > HUMBUG_API_KEY< / span > < span class = "o" > =< / span > < span class = "s" > "0123456789abcdef0123456789abcdef"< / span > < / pre > < / div >
< p > You can also specify which pushes will result in
notifications and to what stream the notifications will be sent
by modifying the < code > commit_notice_destination< / code > function
in < code > humbug_git_config.py< / code > . By default, pushes to
the < code > master< / code > and < code > test-post-receive< / code >
branches will result in a notification to
stream < code > commits< / code > .< / p >
< p > Save < code > integrations/git/humbug_git_config.py< / code > to
the < code > .git/hooks< / code > directory of your git
repository.< / p >
< p > Symlink
< code > /usr/local/share/humbug/integrations/git/post-receive< / code >
into the < code > .git/hooks< / code > directory of your git repository.< / p >
< p > < b > Congratulations! You're done!< / b > < br / > Whenever you make
a push to the < code > master< / code > branch of your git repository
(or whatever you configured above), the Humbug git plugin will
send an automated notification that looks like this:< / p >
< img class = "screenshot" src = "/static/images/integrations/git/001.png" >
< p > < b > Testing< / b > < br / > You can test the plugin without changing
your < code > master< / code > branch by pushing to
the < code > test-post-receive< / code > branch.< / p >
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-03-19 21:22:50 +01:00
{#--------------------------------------------------------------------#}
2013-02-06 20:25:04 +01:00
< div id = "github" class = "integration" >
< h4 > GitHub< / h4 >
< p > First, go to your repository page and click "Settings":< / p >
< img src = "/static/images/integrations/github/001.png" >
< p > From there, select "Service Hooks":< / p >
< img src = "/static/images/integrations/github/002.png" >
2013-02-06 23:12:25 +01:00
< p > Select "Humbug" from the list, fill in the API key and email
address for your bot, check the "active" checkbox, and pick
"Update settings":< / p >
2013-02-06 20:25:04 +01:00
< img src = "/static/images/integrations/github/003.png" >
< p > < b > Congratulations! You're done!< / b > < br / > When people push
to your repository, you'll see a commit message like the
2013-02-10 00:35:31 +01:00
following, to the stream < code > commits< / code > with a subject that matches the repository name (in this case "humbug-test"):< / p >
2013-02-06 23:12:25 +01:00
< img class = "screenshot" src = "/static/images/integrations/github/004.png" >
2013-02-06 20:25:04 +01:00
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-02-10 00:35:06 +01:00
{#--------------------------------------------------------------------#}
< div id = "jenkins" class = "integration" >
< h4 > Jenkins (or Hudson)< / h4 >
2013-02-06 22:31:26 +01:00
2013-04-05 00:15:31 +02:00
< p > Install the "Humbug" plugin by going to < code > Manage Jenkins
> Manage Plugins > Available< / code > , typing in "Humbug", and
clicking "Install without restart".< / p >
2013-02-10 00:35:06 +01:00
< img src = "/static/images/integrations/jenkins/001.png" >
2013-04-05 00:15:31 +02:00
< p > Once the plugin is installed, configure it by going
to < code > Manage Jenkins > Configure System< / code > .< / p >
2013-02-10 00:35:06 +01:00
2013-04-05 00:15:31 +02:00
< img src = "/static/images/integrations/jenkins/002.png" >
2013-02-10 00:35:06 +01:00
2013-04-05 00:15:31 +02:00
< p > 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 < code > jenkins< / code > ).< / p >
2013-02-10 00:35:06 +01:00
< p > The other two options you might want to adjust are "Smart
Notification" (do you want a message after every single build,
2013-04-05 00:15:31 +02:00
or only after a status change?), and "Jenkins URL"— the URL to
2013-02-10 00:35:06 +01:00
your instance of Jenkins, so that we can link you to specific
build reports.< / p >
2013-04-05 00:15:31 +02:00
< img src = "/static/images/integrations/jenkins/003.png" >
2013-02-10 00:35:06 +01:00
< p > 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:< / p >
2013-04-05 00:15:31 +02:00
< img src = "/static/images/integrations/jenkins/004.png" >
2013-02-10 00:35:06 +01:00
< p > 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".< / p >
2013-04-05 00:15:31 +02:00
< img src = "/static/images/integrations/jenkins/005.png" >
2013-02-10 00:35:06 +01:00
< p > < b > Congratulations! You're done!< / b > < br / > 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"):< / p >
2013-04-05 00:15:31 +02:00
< img class = "screenshot" src = "/static/images/integrations/jenkins/006.png" >
< img class = "screenshot" src = "/static/images/integrations/jenkins/007.png" >
< p > < b > Troubleshooting< / b > < / p >
< p > If you don't see the Humbug option in the list, confirm that
the plugin was successfully installed by going to < code > Manage
Jenkins > Manage Plugins > Installed< / code > 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 < a href = "https://wiki.jenkins-ci.org/display/JENKINS/Maven+2+Project+Plugin" > Maven
plugin< / a > installed and try again, or
email < a href = "mailto:support@humbughq.com" > support@humbughq.com< / a >
for help.< / p >
2013-02-10 00:35:06 +01:00
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-03-26 17:04:12 +01:00
{#--------------------------------------------------------------------#}
< div id = "jira" class = "integration" >
< h4 > JIRA< / h4 >
2013-03-27 22:47:54 +01:00
< h5 > Webhook mechanism< / h5 >
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 < a href = "#jira-plugin" > Jira Plugin< / a >
mechanism that supports older versions of JIRA.
< p > In your JIRA administration control panel, go to the Webhooks page. If you are using the OnDemand
2013-03-29 22:57:10 +01:00
hosted JIRA, follow the instructions < a href = "https://developer.atlassian.com/display/JIRADEV/JIRA+Webhooks+Overview#JIRAWebhooksOverview-WhereistheJIRAAdministrationUIforwebhooks?" >
2013-03-27 22:47:54 +01:00
on the Atlassian wiki< / a > for locating the Webhook UI< / a > .
< / p >
< p > Give your new web hook a name, and for the URL provide < code > https://humbughq.com/api/v1/external/jira/API_KEY< / code >
where < code > API_KEY< / code > is the api key of the user you wish to post JIRA updates as.
< / p >
2013-03-29 22:57:10 +01:00
< p > < b > Congratulations! You're done!< / b > < br / >
Updates from JIRA will be sent to the < code > jira< / code > stream, and it must already exist.< / p >
< img class = "screenshot" src = "/static/images/integrations/jira/001.png" >
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
{#--------------------------------------------------------------------#}
< div id = "jira-plugin" class = "integration" >
< h4 > JIRA< / h4 >
< h5 > Plugin mechanism< / h5 >
First, download and install our < a href = "/api" > Python bindings and example scripts< / a > .
2013-03-26 17:04:12 +01:00
< p > < b > Plugin Installation< / b > < / p >
2013-03-29 22:57:10 +01:00
The JIRA integration plugin requires two JIRA plugins. Please install
2013-03-26 17:04:12 +01:00
the following plugins using the Universal Plugin Manager in your JIRA
2013-03-29 22:57:10 +01:00
installation:
2013-03-26 17:04:12 +01:00
< ul >
< li > < a href = "https://marketplace.atlassian.com/plugins/com.onresolve.jira.groovy.groovyrunner" > Script Runner Plugin< / a > < / li >
< li > < a href = "https://marketplace.atlassian.com/plugins/com.atlassian.jira.plugin.jirasslplugin" > SSL Plugin< / a > < / li >
< / ul >
< p > < b > SSL Setup< / b > < / p >
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 < code > Administration > System > Configure SSL< / code > and in
the < code > Import SSL Certificates< / code > field, enter < code > https://www.humbughq.com< / code > . After clicking < code > Save Certificates< / code > ,
follow the on-screen instructions and restart JIRA for it to recognize the proper certificates.
< p > < b > Humbug Integration< / b > < / p >
2013-03-26 23:12:31 +01:00
Copy the folder < code > integrations/jira/org/< / code > (from the tarball you downloaded above) to your JIRA < code > classes< / code > folder.
For self-contained JIRA installations, this will be < code > atlassian-jira/WEB-INF/classes/< / code > , but this may be different in your deployment.< / p >
2013-03-26 17:04:12 +01:00
Edit the constants at the top of < code > org/humbug/jira/HumbugListener.groovy< / code >
and fill them with the appropriate values:
< div class = "codehilite" > < pre > < span class = "n" > String< / span > < span class = "n" > humbugEmail< / span > < span class = "o" > =< / span > < span class = "s2" > "jira-notifications@example.com"< / span >
< span class = "n" > String< / span > < span class = "n" > humbugAPIKey< / span > < span class = "o" > =< / span > < span class = "s2" > "0123456789abcdef0123456789abcdef"< / span >
< span class = "n" > String< / span > < span class = "n" > humbugStream< / span > < span class = "o" > =< / span > < span class = "s2" > "JIRA"< / span >
< span class = "n" > String< / span > < span class = "n" > issueBaseUrl< / span > < span class = "o" > =< / span > < span class = "s2" > "https://jira.COMPANY.com/browse/"< / span >
< / pre > < / div > < / p >
< p > In the Administrators page, navigate to < code > Plugins > Other > Script Listeners< / code > . In the < code > Add Listener< / code > section, click on
the < code > Custom Listener< / code > option. Select the events you wish the Humbug integration to fire for, and the projects you wish Humbug to be notified for.
In the < code > Name of groovy class< / code > field, enter < code > org.humbug.jira.HumbugListener< / code > .
< p > Click < code > Add Listener< / code > , and JIRA will now notify your Humbug of changes to your issues!< / p >
2013-03-29 22:57:10 +01:00
< p > < b > Congratulations! You're done!< / b > < br / >
Updates from JIRA will be sent to the stream you've configured, as below.< / p >
2013-03-26 17:04:12 +01:00
< img class = "screenshot" src = "/static/images/integrations/jira/001.png" >
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-02-13 22:19:08 +01:00
{#--------------------------------------------------------------------#}
< div id = "nagios" class = "integration" >
< h4 > Nagios< / h4 >
< p > First, download and install our < a href = "/api" > Python
bindings and example scripts< / a > on your Nagios server.< / p >
< p > Next, open < code > integrations/nagios/humbugrc.example< / code >
in your favorite editor, and change the following lines to
specify the email address and API key for your Nagios bot,
saving it to < code > /etc/nagios3/humbugrc< / code > on your Nagios
server:< / p >
< div class = "codehilite" > < pre > [api]
email=NAGIOS_EMAIL_ADDRESS
key=NAGIOS_API_KEY
< / pre > < / div >
< p > Copy < code > integrations/nagios/humbug_nagios.cfg< / code >
to < code > /etc/nagios3/conf.d< / code > on your Nagios server.< / p >
< p > Finally, add < code > humbug< / code > to the < code > members< / code >
list for one or more of the contact groups in the < code > CONTACT
GROUPS< / code > section
of < code > /etc/nagios3/conf.d/contacts.cfg< / code > , doing
something like:
< div class = "codehilite" > < pre > define contactgroup{
contactgroup_name admins
alias Nagios Administrators
members monitoring< span class = "na" > , humbug< / span >
}
< / pre > < / div >
Once you've done that, reload your Nagios configuration
using < code > /etc/init.d/nagios3 reload< / code > .< / p >
< p > < b > Congratulations! You're done!< / b > < br / > When your Nagios
system makes an alert, you'll see a message like the following,
to the stream < code > nagios< / code > (to change this, edit the
arguments to < code > nagios-notify-humbug< / code >
in < code > /etc/nagios3/conf.d/humbug_nagios.cfg< / code > ) with a
subject indicating the service with an issue:< / p >
< img class = "screenshot" src = "/static/images/integrations/nagios/001.png" >
< p > < b > Testing< / b > < br / > If you
have < a href = "http://nagios.sourceforge.net/docs/3_0/extcommands.html" > external
commands enabled in Nagios< / a > , you can generate a test notice
from your Nagios instance by visiting using the < code > Send
custom service notification< / code > command in
the < code > Service Commands< / code > section of any individual
service's page on your Nagios instance.< / p >
< p > < b > Troubleshooting< / b > < br / > You can confirm whether you've
correctly configured Nagios to run the Humbug plugin by looking
for < code > SERVICE NOTIFICATION< / code > lines mentioning humbug
in < code > /var/log/nagios3/nagios.log< / code > . You can confirm
whether you've configured the Humbug plugin code correctly by
running < code > /usr/local/share/humbug/integrations/nagios/nagios-notify-humbug< / code >
directly.< / p >
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-02-10 00:35:06 +01:00
{#--------------------------------------------------------------------#}
2013-02-06 22:31:26 +01:00
< div id = "trac" class = "integration" >
< h4 > Trac< / h4 >
2013-02-14 19:46:23 +01:00
< p > First, download and install our < a href = "/api" > Python
bindings and example scripts< / a > on your Trac server.< / p >
2013-02-06 22:31:26 +01:00
2013-02-14 19:46:23 +01:00
< p > Next, open < code > integrations/trac/humbug_trac_config.py< / code > in
2013-02-13 22:48:16 +01:00
your favorite editor, and change the following lines to specify
your bot's email address, API key, and where you'd like your
2013-02-06 22:31:26 +01:00
notification messages to go (by default,
stream < code > trac< / code > ):< / p >
< div class = "codehilite" > < pre > < span class = "n" > HUMBUG_USER< / span > < span class = "o" > =< / span > < span class = "s" > "trac-notifications@example.com"< / span >
< span class = "n" > HUMBUG_API_KEY< / span > < span class = "o" > =< / span > < span class = "s" > "0123456789abcdef0123456789abcdef"< / span >
< span class = "n" > STREAM_FOR_NOTIFICATIONS< / span > < span class = "o" > =< / span > < span class = "s" > "trac"< / span >
< span class = "n" > TRAC_BASE_TICKET_URL< / span > < span class = "o" > =< / span > < span class = "s" > "https://trac.example.com/ticket"< / span > < / pre > < / div >
2013-02-14 19:46:23 +01:00
< p > Copy < code > integrations/trac/humbug_trac.py< / code >
and < code > integrations/trac/humbug_trac_config.py< / code > into
your Trac installation's < code > plugins/< / code >
subdirectory. Once you've done that, edit your Trac
installation's < code > conf/trac.ini< / code > to
add < code > humbug_trac< / code > to the < code > [components]< / code >
section, as follows:< / p >
2013-02-06 22:31:26 +01:00
< div class = "codehilite" > < pre > < span class = "k" > [components]< / span >
< span class = "na" > humbug_trac< / span > < span class = "o" > =< / span > < span class = "s" > enabled< / span > < / pre > < / div >
< p > You may then need to restart Trac (or Apache) so that Trac will load our plugin.< / p >
< p > < b > Congratulations! You're done!< / b > < br / > When people open
new tickets (or edit existing tickets), you'll see a message
like the following, to the stream < code > trac< / code > (or whatever
you configured above) with a subject that matches the ticket
name:< / p >
2013-02-06 23:12:25 +01:00
< img class = "screenshot" src = "/static/images/integrations/trac/001.png" >
2013-02-06 22:31:26 +01:00
2013-02-13 22:48:16 +01:00
< p > < b > Additional trac configuration< / b > < br / > After using the plugin
for a while, you may want to customize which changes to tickets
result in a Humbug notification using
the < code > TRAC_NOTIFY_FIELDS< / code > setting
in < code > humbug_trac_config.py< / code > .< / p >
2013-02-06 22:31:26 +01:00
< p >
< a href = "#services" > ^ Back to top< / a >
< / p >
< / div >
2013-02-06 20:25:04 +01:00
< / div >
2013-04-02 20:01:23 +02:00
{% endblock %}
{% block customhead %}
{{ block.super }}
2013-02-06 20:25:04 +01:00
< script type = "text/javascript" >
$(function() {
$("a.title").addClass("show-integral");
2013-02-11 22:34:20 +01:00
$("a.title").prepend($("< span class = 'integral' > ∫< / span > "));
$("a.title").hover(function (e) {
$(".integral").css("display", "inline");
var width = $(".integral").width();
$("a.title").css("left", -1 * width);
},
function (e) {
$(".integral").css("display", "none");
$("a.title").css("left", 0);
});
2013-02-06 20:25:04 +01:00
});
< / script >
{% endblock %}
