mirror of https://github.com/zulip/zulip.git
286 lines
12 KiB
HTML
286 lines
12 KiB
HTML
{% extends "zephyr/portico.html" %}
|
|
|
|
{# API information page #}
|
|
|
|
{% block customhead %}
|
|
{{ block.super }}
|
|
<link rel="stylesheet" href="/static/styles/pygments.css" />
|
|
{% endblock %}
|
|
|
|
{% block portico_content %}
|
|
<div class="row-fluid">
|
|
<div class="span8">
|
|
<h2>Integrations</h2>
|
|
|
|
<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>
|
|
|
|
<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
|
|
account, or
|
|
<a href="{% url zephyr.views.accounts_home %}">register</a> a new
|
|
one for them. (If new email addresses are hard to come by, you can
|
|
use something like <code>wdaher+github@example.com</code>.)</p>
|
|
|
|
<h3 id="services">Services with integrations</h3>
|
|
<ul>
|
|
{% comment %}
|
|
<li><a href="#git">Git</a></li>
|
|
{% endcomment %}
|
|
<li><a href="#github">GitHub</a></li>
|
|
<li><a href="#jenkins">Jenkins (or Hudson)</a></li>
|
|
<li><a href="#nagios">Nagios</a></li>
|
|
{% comment %}
|
|
<li><a href="#pivotal">Pivotal Tracker</a></li>
|
|
<li><a href="#svn">Subversion</a></li>
|
|
{% endcomment %}
|
|
<li><a href="#trac">Trac</a></li>
|
|
{% comment %}
|
|
<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>
|
|
|
|
<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">
|
|
|
|
<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>
|
|
<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
|
|
following, to the stream <code>commits</code> with a subject that matches the repository name (in this case "humbug-test"):</p>
|
|
<img class="screenshot" src="/static/images/integrations/github/004.png">
|
|
|
|
<p>
|
|
<a href="#services">^ Back to top</a>
|
|
</p>
|
|
</div>
|
|
{#--------------------------------------------------------------------#}
|
|
<div id="jenkins" class="integration">
|
|
<h4>Jenkins (or Hudson)</h4>
|
|
|
|
<p>Download
|
|
the <a href="https://humbughq.com/dist/integrations/jenkins/humbug-jenkins-0.1.1.hpi">Humbug
|
|
Jenkins plugin</a>. To install the plugin, select "Manage
|
|
Jenkins", "Manage Plugins", and then "Advanced". Under the
|
|
section labeled "Upload Plugin",
|
|
select <code>humbug-jenkins-0.1.hpi</code> from your computer,
|
|
and upload it:</p>
|
|
|
|
<img src="/static/images/integrations/jenkins/001.png">
|
|
<hr />
|
|
<img src="/static/images/integrations/jenkins/002.png">
|
|
<hr />
|
|
<img src="/static/images/integrations/jenkins/003.png">
|
|
<hr />
|
|
<img src="/static/images/integrations/jenkins/004.png">
|
|
|
|
<p>After uploading the plugin, restart Jenkins for the
|
|
installation to take effect. Some versions of Jenkins have a
|
|
link to restart on the "Install" tab of the "Manage Plugins"
|
|
page. If your version does not, and you have access to a shell
|
|
on the computer running Jenkins, <code>service jenkins
|
|
restart</code> will restart it on a Linux system.</p>
|
|
|
|
<p>Once Jenkins has restarted, it's time to configure our
|
|
plugin. Go to "Manage Jenkins" and then to "Configure
|
|
System".</p>
|
|
|
|
<img src="/static/images/integrations/jenkins/005.png">
|
|
|
|
<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,
|
|
e.g. stream <code>jenkins</code>).</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<img src="/static/images/integrations/jenkins/006.png">
|
|
|
|
<p>(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
|
|
"Jenkins 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>
|
|
|
|
<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>
|
|
|
|
<img src="/static/images/integrations/jenkins/007.png">
|
|
|
|
<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>
|
|
|
|
<img src="/static/images/integrations/jenkins/008.png">
|
|
|
|
<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>
|
|
<img class="screenshot" src="/static/images/integrations/jenkins/009.png">
|
|
<img class="screenshot" src="/static/images/integrations/jenkins/010.png">
|
|
|
|
<p>
|
|
<a href="#services">^ Back to top</a>
|
|
</p>
|
|
</div>
|
|
|
|
{#--------------------------------------------------------------------#}
|
|
<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>
|
|
|
|
{#--------------------------------------------------------------------#}
|
|
<div id="trac" class="integration">
|
|
<h4>Trac</h4>
|
|
<p>First, download and install our <a href="/api">Python
|
|
bindings and example scripts</a> on your Trac server.</p>
|
|
|
|
<p>Next, open <code>integrations/trac/humbug_trac_config.py</code> 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 <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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
<img class="screenshot" src="/static/images/integrations/trac/001.png">
|
|
|
|
<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>
|
|
|
|
<p>
|
|
<a href="#services">^ Back to top</a>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
|
|
<script type="text/javascript">
|
|
$(function() {
|
|
$("a.title").addClass("show-integral");
|
|
$("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);
|
|
});
|
|
});
|
|
</script>
|
|
{% endblock %}
|