zulip/templates/zephyr/integrations.html

{% extends "zephyr/portico.html" %}

{# API information page #}

{% 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&mdash;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>
      <li><a href="#git">Git</a></li>
      <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="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>

    <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.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 %}