zulip/templates/zerver/integrations.html

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

{# API information page #}

{% block portico_content %}
<div class="row-fluid">
  <div class="span8">
    <h1>Integrations</h1>
    <ul class="breadcrumb">
      <li><a href="/">Home</a> <span class="divider">/</span></li>
      <li class="active">Integrations</li>
    </ul>

    <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 Zulip 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 id="services">Services with integrations</h3>
    <ul>
      <li><a href="#basecamp">Basecamp</a></li>
      <li><a href="#beanstalk">Beanstalk</a></li>
      <li><a href="#bitbucket">Bitbucket</a></li>
      <li><a href="#capistrano">Capistrano</a></li>
      <li><a href="#desk">Desk.com</a></li>
      <li><a href="#email">Email</a></li>
      <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="#jira">Jira (hosted or v5.2+)</a></li>
      <li><a href="#jira-plugin">Jira (locally installed)</a></li>
      <li><a href="#nagios">Nagios</a></li>
      <li><a href="#newrelic">New Relic</a></li>
      <li><a href="#pivotal">Pivotal Tracker</a></li>
      <li><a href="#svn">Subversion</a></li>
      <li><a href="#trac">Trac</a></li>
      <li><a href="#trello">Trello</a></li>
      {% comment %}
      <li><a href="#twitter">Twitter</a></li>
      {% endcomment %}
      <li>...and more coming soon! <a href="mailto:support@zulip.com?subject=Integration%20request">Email us</a> with requests!</li>
    </ul>

    <h3>Getting started</h3>
    <p>First, create a bot from your <a href="/#settings"
    target="_blank">settings page</a>. Look for the bot's email and
    API key: <img class="screenshot"
    src="/static/images/api/bot-key.png" /></p>

    <p>The bot email address doesn't actually need to be a valid email
    address.</p>

    <p>Then, follow the integration instructions below for the service
    you are interested in. It's as easy as that! If you run into any
    trouble, don't hesitate
    to <a href="mailto:support@zulip.com?subject=Integration%20question">email
    us</a>.</p>

    {#--------------------------------------------------------------------#}
    <div id="basecamp" class="integration">
      <h4>Basecamp</h4>
      <p>First, create the stream you'd like to use for Basecamp notifications,
      and subscribe all interested parties to this stream. We recommend the
      name <code>basecamp</code>.</p>

      <p>Next, download and install our <a href="/api">Python
          bindings and example scripts</a> on the computer you'd like to run this mirroring script from.</p>

      <p>You will need your Basecamp account ID. You can find it as a sequence of numbers in the URL when you log in:</p>
      <img class="screenshot" src="/static/images/integrations/basecamp/001.png">
      <p>Edit the Basecamp and Zulip credentials in <code>integrations/basecamp/zulip_basecamp_config.py</code> using
      your favorite editor:


      <div class="codehilite">
      <pre><span class="n">BASECAMP_ACCOUNT_ID</span> <span class="o">=</span> <span class="s">"1234567"</span>
<span class="n">BASECAMP_USERNAME</span> <span class="o">=</span> <span class="s">"foo@example.com"</span>
<span class="n">BASECAMP_PASSWORD</span> <span class="o">=</span> <span class="s">"p455w0rd"</span>

<span class="n">ZULIP_USER</span> <span class="o">=</span> <span class="s">"basecamp-bot@example.com"</span>
<span class="n">ZULIP_API_KEY</span> <span class="o">=</span> <span class="s">"0123456789abcdef0123456789abcdef"</span></pre>
      </div>

      <p>Before your first run of the script, you may optionally choose to
      configure it to mirror some number of hours of Basecamp activity:</p>

      <div class="codehilite">
        <pre><span class="n">BASECAMP_INITIAL_HISTORY_HOURS</span> <span class="o">=</span> <span class="s">10</span></pre>
      </div>

      <p>Now, simply run the <code>api/integrations/basecamp/zulip_basecamp_mirror</code> script.
      If needed, this script may be restarted, and it will automatically resume from when
      it was last running.</p>

      <p><b>Congratulations! You're done!</b><br /> Whenever you create a new project,
      calendar event, comment, message, or more, you'll get a notification in your selected stream
      with the project or calendar as the topic.
      <img class="screenshot" src="/static/images/integrations/basecamp/002.png">
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
    {#--------------------------------------------------------------------#}
    <div id="beanstalk" class="integration">
      <h4>Beanstalk</h4>
     <p>Zulip supports both SVN and Git notifications from Beanstalk.</p>

     <p>First, create the stream <code>commits</code> and subscribe all
     interested parties to this stream.</p>

     <p>Next, in the Beanstalk web application, go to the Setup page and choose the Integrations tab.
     Choose the <code>Webhooks</code> integration from the list presented. Make sure to replace the <code>@</code> in the bot's email address with <code>%40</code>,
     as Beanstalk's website will incorrectly refuse to parse a username containing a <code>@</code>.</p>

     <p>In the URL field, enter <code>https://bot_email:bot_api_key@api.zulip.com/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>
    {#--------------------------------------------------------------------#}
    <div id="bitbucket" class="integration">
      <h4>Bitbucket</h4>

     <p>Zulip supports both Git and Mercurial notifications from Bitbucket.</p>

     <p>First, create the stream you'd like to use for Bitbucket notifications,
     and subscribe all interested parties to this stream. The integration will
     use the default stream <code>commits</code> if no stream is supplied in the
     hook; you still need to create the stream even if you are using this
     default.</p>

     <p>Next, from your repository's web page, go to the Administration page and choose Hooks on the left-hand side.
     Choose the <code>POST</code> hook from the list presented and click "Add hook."   Make sure to replace the <code>@</code> in the bot's email address with <code>%40</code>,
     as Bitbucket will not execute the hook if the username contains a <code>@</code>.</p>

      <p>In the URL field, enter <code>https://bot_email:bot_api_key@api.zulip.com/v1/external/bitbucket</code>:</p>
      <img class="screenshot" src="/static/images/integrations/bitbucket/001.png">

      <p>By default, notifications are sent to the <code>commits</code> stream.
      To send notifications to a different stream,
      append <code style="white-space: nowrap;">?stream=stream_name</code> to
      the URL.</p>

      <p><b>Congratulations! You're done!</b><br /> Whenever you push code to your repository,
        you'll get an automated notification that looks like this:</p>
      <img class="screenshot" src="/static/images/integrations/bitbucket/002.png">
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
    {#--------------------------------------------------------------------#}
    <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>zulip-send</code>
      utility to notify you when certain events happen.</p>

      <p>Here's some example code for sending a Zulip notification
      after a deployment has completed:</p>
<div class="codehilite"><pre><span class="n">after</span> <span class="s1">'deploy'</span><span class="p">,</span> <span class="s1">'notify:humbug'</span>

<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 Zulip 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 Zulip as the user defined in
    # ~/.zuliprc if you omit --user and --api-key</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:' | zulip-send \
    --user capistrano-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
    --stream commits --subject deployments || true"</span>
  <span class="k">end</span>
<span class="k">end</span>
</pre></div>

      <p>Some notes:</p>
      <ul>
        <li>If you prefer not to use <code>--user</code> and <code>--api-key</code> above, you can fill out <code>~/.zuliprc</code> on your Capistrano
      machine. For instructions on how to write that file, see <a href="/api">the API page</a>.</li>
        <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>
      </ul>
<em></em>

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

{#--------------------------------------------------------------------#}
    <div id="desk" class="integration">
      <h4>Desk.com</h4>

      <p>First, create the stream you'd like to use for Desk.com notifications,
      and subscribe all interested parties to this stream. We recommend the
      stream name <code>desk</code>. Keep in mind you still need to
      create the stream first even if you are using this recommendation.</p>

      <p>Next, in Desk.com, open your Admin view via the top-left corner
      dropdown. In the Admin view, click on Apps, then click Install under
      "Custom Action":</p>
      <img src="/static/images/integrations/desk/001.png">

      <p>From there, click "Install Custom Action" and accept the terms. Fill
      in the form like this:</p>
      <ul>
          <li><b>Name</b>: Zulip</li>
          <li><b>Authentication Method</b>: Basic Auth</li>
          <li><b>URL</b>: <code>https://zulip.com/api/v1/external/desk</code></li>
          <li><b>User name</b>: <em>your bot's user name, e.g.</em> <code>desk-bot@yourdomain.com</code></li>
          <li><b>Password</b>: <em>your bot's API key</em></li>
      </ul>

      <img src="/static/images/integrations/desk/002.png">

      <p>From here, add a new action. You'll do this for every action you
      want a notification on Zulip for:</p>
      <img src="/static/images/integrations/desk/003.png">

      <p>Let's say you want a notification each time a case is updated. Put
      in a descriptive name like "Announce case update", and copy-paste
      this to the "Appended URL path":</p>
      {% verbatim %}
      <p><code>?stream=desk&amp;topic={{case.id}}:+{{case.subject}}</code></p>
      {% endverbatim %}
      <p>The "appended URL path" will be the same for every notification —
      it makes sure the notification goes to the appropriate stream and topic
      within Zulip. Next, copy this template Zulip message into "Message to
      POST":</p>
      {% verbatim %}
      <pre><code
>Case [{{case.id}}, {{case.subject}}]({{case.direct_url}}), was updated.

* Status: {{case.status.name}}
* Priority: {{case.priority}}
* Customer: {{customer.name}}
* Company: {{customer.company}}
* Description: {{case.description}}</code></pre>
      <p>You don't need to edit that. All the funny-looking stuff inside
      <code>{{</code> and <code>}}</code>
      will be filled in by Desk.com for each event. The dialog should look
      like this:</p>
      {% endverbatim %}
      <img src="/static/images/integrations/desk/004.png">

      <p>Save it, and then click "On" next to the action to enable it. This
      is important — actions are turned off by default!</p>

      <p>Now you need to create a rule that triggers this action. Desk.com's
      support center has a
      <a href="https://support.desk.com/customer/portal/articles/1376">lengthy
          article on rules</a>, but in short, click on "Cases" up at the top,
      "Rules" on the left side, and then the specific event you want to notify
      on — in our example, "Case Updated". Add a rule with a name like "Notify
      Zulip of case update". Click on "Add Action", select "Trigger an App
      Action", and select "Zulip: Announce case update". Set "Enabled" to
      "Yes". The rule should look like this:</p>
      <img src="/static/images/integrations/desk/005.png">

      <p>Finally, click Update.</p>

      <p><b>Congratulations! You're done!</b><br /> When a case is updated,
      you'll see a notification like the following, to the stream
      <code>desk</code>, with a topic that matches the case's subject name:</p>
      <img class="screenshot" src="/static/images/integrations/desk/006.png">

      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>


{#--------------------------------------------------------------------#}
    <div id="email" class="integration">
      <h4>Email <img src="/static/images/integrations/zulip_mail.png" style="width: 50px;" /></h4>

      <p>You can send emails to Zulip! This is useful:</p>

      <ul>
        <li>If you use a service that can send emails but does not easily lend
        itself to more direct integration</li>
        <li>If you have an email that you want to discuss on Zulip</li>
        <li>As a structured, searchable, commentable archive for mailing list
        traffic</li>
      </ul>

      <p>To send an email to a Zulip stream:</p>

      <ol>
        <li>visit your <a target="_blank" href="../#subscriptions">subscriptions
        page</a> and click on the stream row to expand it.</li>
        <li>Copy the stream email address
        (e.g. <code>support+abcdefg@streams.zulip.com</code>). If the stream
        name contains special characters, we've transformed the name so it is a
        safe email recipient.</li>
        <li>Send an email (To, CC, and BCC all work) to the stream email
        address. The email subject will become the stream topic, and the email
        body will become the Zulip message content.</li>
      </ol>

      <p>Please note that it may take up to one minute for the message to show up
      in Zulip.</p>

      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>

{#--------------------------------------------------------------------#}
    <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, create the stream you'd like to use for Git notifications, and
      subscribe all interested parties to this stream. The integration will use
      the default stream <code>commits</code> if no stream is supplied in the
      hook; you still need to create the stream even if you are using this
      default.</p>

      <p>Next, open <code>integrations/git/zulip_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">ZULIP_USER</span> <span class="o">=</span> <span class="s">"git-bot@example.com"</span>
<span class="n">ZULIP_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>zulip_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/zulip_git_config.py</code> to
      the <code>.git/hooks</code> directory of your git
      repository.</p>

      <p>Symlink
      <code>/usr/local/share/zulip/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 Zulip 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, create the stream you'd like to use for GitHub notifications,
      and subscribe all interested parties to this stream. The integration will
      use the default stream <code>commits</code> if no stream is supplied in
      the hook; you still need to create the stream even if you are using this
      default.</p>

      <p>Next, 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>First, create the stream you'd like to use for Jenkins or Hudson
      notifications, and subscribe all interested parties to this stream. We
      recommend the name <code>jenkins</code> or <code>hudson</code>.</p>

      <p><strong>Install the plugin</strong><br />
      Install the "Humbug" plugin by going to <code>Manage Jenkins
      > Manage Plugins > Available</code>, typing in "Humbug", and
      clicking "Install without restart".</p>

      <img src="/static/images/integrations/jenkins/001.png">

      <p><strong>Configure the plugin</strong><br /> Once the plugin
      is installed, configure it by going to <code>Manage Jenkins >
      Configure System</code>. Scroll to the section labeled "Humbug
      Notification Settings", and specify your bot's email address,
      API key, the stream receiving the notifications, and whether you'd
      like a notification on every build, or only when the build fails
      (Smart Notification).</p>

      <img src="/static/images/integrations/jenkins/002.png">

      <p><strong>Configure a post-build action for your project</strong><br />
      Once you've done that, it's time to configure one of your
      projects to use the Zulip notification plugin. From your
      project page, click "Configure" on the left sidebar. 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/003.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/004.png">
      <img class="screenshot" src="/static/images/integrations/jenkins/005.png">

      <p><b>Troubleshooting</b><br />
        <ul>
          <li>Did you set up a post-build action for your project?</li>
          <li>Does the stream you picked (e.g. <code>jenkins</code>) already exist? If not, add yourself to it and try again.</li>
          <li>Are your access key and email address correct? Test them using <a href="/api">our curl API</a>.
          <li>Still stuck? Email <a href="mailto:support@zulip.com?subject=Jenkins">support@zulip.com</a>.</li>
        </ul>
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
   <div id="jira" class="integration">
      <h4>JIRA</h4>

      <p><em>If you are running JIRA version 5.2 or greater, or if you are
          using the hosted JIRA provided by Atlassian, you can use the built-in
          web-hook support to connect to Zulip &mdash; read on. For older,
          self-hosted JIRA installs, you can use our <a
              href="#jira-plugin">JIRA Plugin</a>.</em></p>

      <p>First, create the stream you'd like to use for JIRA notifications, and
      subscribe all interested parties to this stream. We recommend the
      name <code>jira</code>.</p>

      <p>In your JIRA administration control panel, go to the Webhooks page. If you are using the OnDemand
        hosted JIRA, follow the instructions <a href="https://developer.atlassian.com/display/JIRADEV/JIRA+Webhooks+Overview#JIRAWebhooksOverview-WhereistheJIRAAdministrationUIforwebhooks?">
        on the Atlassian wiki</a> for locating the Webhook UI.
      </p>
      <p>Give your new web hook a name, and for the URL provide the following:</p>
      <p>
      <code>https://api.zulip.com/v1/external/jira?api_key=abcdefgh&amp;stream=jira</code>
      </p>

      <p>where <code>api_key</code> is the API key of your Zulip bot,
      and <code>stream</code> is the stream name you want the
      notifications sent to.</p>

      <p>Next, go back to Zulip and set up a stream called "jira," if it does not already exist.
      (If you prefer your JIRA notifications to go to a stream other than "jira," then change the URL above to match it.)</p>

      <p><b>Congratulations! You're done!</b><br />
      Updates from JIRA will be sent to the Zulip stream you specified in the JIRA web-hook.
      <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 (Plugin)</h4>

      <p><em>If you are running JIRA version 5.2 or greater, or using the
          hosted JIRA provided by Atlassian, we recommend using the <a
              href="#jira">web-hook method</a> above instead. This plugin
          supports older versions of JIRA.</em></p>

      <p>First, create the stream you'd like to use for JIRA notifications, and
      subscribe all interested parties to this stream. We recommend the
      name <code>jira</code>.</p>

      <h5>Plugin mechanism</h5>
      Next, download and install our <a href="/api">Python bindings and example scripts</a>.
      <p><b>Plugin Installation</b></p>
        The JIRA integration plugin requires two JIRA plugins. Please install
        the following plugins using the Universal Plugin Manager in your JIRA
        installation:
        <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 Zulip 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://api.zulip.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>Zulip Integration</b></p>
        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.
        Edit the constants at the top of <code>org/zulip/jira/ZulipListener.groovy</code>
        and fill them with the appropriate values:
<div class="codehilite"><pre><span class="n">String</span> <span class="n">zulipEmail</span> <span class="o">=</span> <span class="s2">"jira-notifications-bot@example.com"</span>
<span class="n">String</span> <span class="n">zulipAPIKey</span> <span class="o">=</span> <span class="s2">"0123456789abcdef0123456789abcdef"</span>
<span class="n">String</span> <span class="n">zulipStream</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>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 Zulip integration to fire for, and the projects you wish Zulip to be notified for.
        In the <code>Name of groovy class</code> field, enter <code>org.zulip.jira.ZulipListener</code>.

      <p>Click <code>Add Listener</code>, and JIRA will now notify your Zulip of changes to your issues!</p>

      <p><b>Congratulations! You're done!</b><br />
      Updates from JIRA will be sent to the stream you've configured, as below.</p>
      <img class="screenshot" src="/static/images/integrations/jira/001.png">
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
    <div id="nagios" class="integration">
      <h4>Nagios</h4>

      <p>First, create the stream you'd like to use for Nagios notifications,
      and subscribe all interested parties to this stream. The integration will
      use the default stream <code>nagios</code> if no stream is supplied in the
      configuration; you still need to create the stream even if you are using
      this default.</p>

      <p>Next, download and install our <a href="/api">Python
      bindings and example scripts</a> on your Nagios server.</p>

      <p>Next, open <code>integrations/nagios/zuliprc.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/zuliprc</code> on your Nagios
      server:</p>

<div class="codehilite"><pre>[api]
email=NAGIOS_BOT_EMAIL_ADDRESS
key=NAGIOS_BOT_API_KEY
</pre></div>

      <p>Copy <code>integrations/nagios/zulip_nagios.cfg</code>
      to <code>/etc/nagios3/conf.d</code> on your Nagios server.</p>

      <p>Finally, add <code>zulip</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">, zulip</span>
        }
</pre></div>

      Once you've done that, reload your Nagios configuration
      using <code>/etc/init.d/nagios3 reload</code>.

      <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-zulip</code>
      in <code>/etc/nagios3/conf.d/zulip_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 Zulip plugin by looking
      for <code>SERVICE NOTIFICATION</code> lines mentioning zulip
      in <code>/var/log/nagios3/nagios.log</code>.  You can confirm
      whether you've configured the Zulip plugin code correctly by
      running <code>/usr/local/share/zulip/integrations/nagios/nagios-notify-zulip</code>
      directly.</p>

      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
    <div id="pivotal" class="integration">
      <h4>Pivotal Tracker</h4>

      <p>Zulip supports Pivotal Tracker integration and can notify you of changes
      to the stories in your Pivotal Tracker project.</p>

      <p>First, create the stream you'd like to use for Pivotal Tracker
      notifications, and subscribe all interested parties to this stream. We
      recommend the name <code>pivotal</code>.</p>

      <p>Next, in the Settings page for your project, choose the Integrations
      tab. Scroll down to the <code>Activity Web Hook</code> section, and enter
      the following url:</p>

      <p><code>https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&amp;stream=pivotal</code></p>

      <p>where <code>api_key</code> is the API key of your Zulip bot,
      and <code>stream</code> is the stream name you want the
      notifications sent to.</p>

      <img class="screenshot" src="/static/images/integrations/pivotal/001.png">

      <p><b>Congratulations! You're done!</b><br /> When you make changes in Pivotal Tracker they will be reflected in Zulip:
      <img class="screenshot" src="/static/images/integrations/pivotal/002.png">
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
    <div id="newrelic" class="integration">
     <h4>New Relic</h4>

      <p>New Relic can send messages to a Zulip stream for alerts and
      deploys.</p>

      <p>First, create the stream you'd like to use for New Relic
      notifications, and subscribe all interested parties to this stream. We
      recommend the name <code>newrelic</code>.</p>

      <p>Next, in your New Relic Account Settings page, click
      "Integrations", then "Alerting notifications". On the "Webhook"
      tab, enter the following webhook URL:</p>

      <p><code>https://api.zulip.com/v1/external/newrelic?api_key=abcdefgh&amp;stream=newrelic</code></p>

      <p>where <code>api_key</code> is the API key of your Zulip bot,
      and <code>stream</code> is the stream name you want the
      notifications sent to.</p>

      <img class="screenshot" src="/static/images/integrations/newrelic/001.png">

      <p><b>Congratulations! You're done!</b><br /> Your New Relic events will
       appear in Zulip:
      <img class="screenshot" src="/static/images/integrations/newrelic/002.png">
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
    <div id="svn" class="integration">
      <h4>Subversion</h4>

      <p>It is easy to send Zulips on SVN commits, by configuring a post-commit
      hook. To do this:</p>

      <p>First, create the stream you'd like to use for SVN commit
      notifications, and subscribe all interested parties to this stream. The
      integration will use the default stream <code>commits</code> if no stream
      is supplied in the hook; you still need to create the stream even if you
      are using this default.</p>

      <p>Then:</p>

      <ol>
        <li>Download and install our <a href="/api">Python bindings</a> on the
        server where the SVN repository lives.</li>
        <li>Install <code>pysvn</code>. On Linux, you can install
        the <code>python-svn</code> package. On other platforms, you can install
        a binary or from source following
        the <a href="http://pysvn.tigris.org/project_downloads.html">instructions
        on the pysvn website</a>.</li>
        <li>Copy <code>integrations/svn/zulip_svn_config.py</code>
        and <code>integrations/svn/post-commit</code> from the API bindings
        directory to the <code>hooks</code> subdirectory of your SVN
        repository.</li>
        <li>Open <code>zulip_svn_config.py</code> in your favorite editor and
        change the <code>ZULIP_USER</code> and <code>ZULIP_API_KEY</code>
        variables at the top of the file to the credentials for the bot you'd
        like to use for this integration.</li>
        <li>The default stream used by this post-commit hook
        is <code>commits</code>; if you'd prefer a different stream, change it
        now in <code>zulip_svn_config.py</code>. Make sure that everyone
        interested in getting these post-commit Zulips is subscribed to that
        stream!</li>
      </ol>

      <p><b>Congratulations! You're done!</b><br /> When you commit to this SVN
      repository, the team can see these updates in real time in Zulip:</p>

      <img class="screenshot" src="/static/images/integrations/svn/001.png">
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
    <div id="trac" class="integration">
      <h4>Trac</h4>

      <p>First, create the stream you'd like to use for Trac notifications, and
      subscribe all interested parties to this stream. The integration will use
      the default stream <code>trac</code> if no stream is supplied in the
      hook; you still need to create the stream even if you are using this
      default.</p>

      <p>Next, download and install our <a href="/api">Python
      bindings and example scripts</a> on your Trac server.</p>

      <p>Next, open <code>integrations/trac/zulip_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">ZULIP_USER</span> <span class="o">=</span> <span class="s">"trac-notifications-bot@example.com"</span>
<span class="n">ZULIP_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/zulip_trac.py</code>
      and <code>integrations/trac/zulip_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>zulip_trac</code> to the <code>[components]</code>
      section, as follows:</p>

<div class="codehilite"><pre><span class="k">[components]</span>
<span class="na">zulip_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 Zulip notification using
      the <code>TRAC_NOTIFY_FIELDS</code> setting
      in <code>zulip_trac_config.py</code>.</p>

      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
    <div id="trello" class="integration">
      <h4>Trello</h4>

      <p>First, create the stream you'd like to use for Trello notifications,
      and subscribe all interested parties to this stream. We recommend the
      name <code>trello</code>.</p>

      <p>Next, download a copy
      of <a href="https://github.com/nathanlws/trello-to-zulip">trello-to-zulip</a>
      and follow the instructions in <code>README.md</code>. When you
      make changes in Trello, they will be reflected in Zulip:
      </p>

      <img class="screenshot" src="/static/images/integrations/trello/001.png">
      <p><small>Thanks to Nathan from FoundationDB for <a href="https://github.com/nathanlws/trello-to-zulip">submitting this integration</a>!</small></p>
      <p>
        <a href="#services">^ Back to top</a>
      </p>
    </div>
{#--------------------------------------------------------------------#}
  </div>
</div>

{% endblock %}

{% block customhead %}
{{ block.super }}
<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 %}