mirror of https://github.com/zulip/zulip.git
950 lines
45 KiB
HTML
950 lines
45 KiB
HTML
{% extends "zerver/portico.html" %}
|
|
|
|
{# API information page #}
|
|
|
|
{% block portico_content %}
|
|
<div class="integrations-page-header">Integrations</div>
|
|
|
|
<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—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="#codebase">Codebase HQ</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="#phabricator">Phabricator</a></li>
|
|
<li><a href="#pivotal">Pivotal Tracker</a></li>
|
|
<li><a href="#redmine">Redmine</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="codebase" class="integration">
|
|
<h4>Codebase HQ</h4>
|
|
<p>First, create the streams you'd like to use for Codebase notifications. There will be two types of
|
|
messages: commit-related updates and issue-related updates. After creating these streams (we suggest naming
|
|
them <code>codebase commits</code> and <code>codebase issues</code>), make sure to subscribe all interested parties.</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 Codebase API Username. You can find it in the settings page of your account, under
|
|
<code>API Credentials</code>.</p>
|
|
<p>Edit the Codebase and Zulip credentials in <code>integrations/codebase/zulip_codebase_config.py</code> using
|
|
your favorite editor:</p>
|
|
|
|
|
|
<div class="codehilite">
|
|
<pre><span class="n">CODEBASE_API_USERNAME</span> <span class="o">=</span> <span class="s">"zulip-inc/leo-franchi-15"</span>
|
|
<span class="n">CODEBASE_API_KEY</span> <span class="o">=</span> <span class="s">0123456789abcdef0123456789abcdef</span>
|
|
|
|
<span class="n">ZULIP_USER</span> <span class="o">=</span> <span class="s">"codebase-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 prior Codebase activity:</p>
|
|
|
|
<div class="codehilite">
|
|
<pre><span class="n">CODEBASE_INITIAL_HISTORY_HOURS</span> <span class="o">=</span> <span class="s">10</span></pre>
|
|
</div>
|
|
|
|
<p>Now, simply run the <code>api/integrations/codebase/zulip_codebase_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,
|
|
commit, issue, deployment, or more, you'll get notifications in your selected streams
|
|
with the associated information.</p>
|
|
<img class="screenshot" src="/static/images/integrations/codebase/001.png">
|
|
<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&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 — 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&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="phabricator" class="integration">
|
|
<h4>Phabricator</h4>
|
|
|
|
<p>Zulip supports Phabricator integration and can notify you of the
|
|
latest items in your Phabricator feed.</p>
|
|
|
|
<p>You can follow the instructions at
|
|
<a href="https://github.com/zulip/phabricator-to-zulip">
|
|
https://github.com/zulip/phabricator-to-zulip
|
|
</a>
|
|
to get it set up.
|
|
|
|
</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&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&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="redmine" class="integration">
|
|
<h4>Redmine</h4>
|
|
|
|
<p>Get information on new or updated Redmine issues right in
|
|
Zulip with our Zulip Redmine plugin! Note: this setup must be
|
|
done by a Redmine Administrator.</p>
|
|
|
|
<p>First, create the stream you'd like to use for Redmine notifications,
|
|
and subscribe all interested parties to this stream. We recommend the
|
|
name <code>redmine</code>.</p>
|
|
|
|
<p>Then:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Clone
|
|
the <a href="https://github.com/zulip/zulip-redmine-plugin">Zulip
|
|
Redmine plugin repository</a> by running:</p>
|
|
<pre>git clone https://github.com/zulip/zulip-redmine-plugin</pre>
|
|
</li>
|
|
<li>
|
|
<p>Follow
|
|
the <a href="http://www.redmine.org/projects/redmine/wiki/Plugins">Redmine
|
|
plugin installation guide</a> to install
|
|
the <code>zulip_redmine</code> plugin directory, which is a
|
|
subdirectory of the <code>zulip-redmine-plugin</code> repository
|
|
directory. In a nutshell, the steps are:</p>
|
|
<ol type="A">
|
|
<li>
|
|
<p>Copy the <code>zulip_redmine</code> directory to
|
|
the <code>plugins</code> directory of your Redmine
|
|
instance.</p></li>
|
|
<li>
|
|
<p>Update the Redmine database by running (for Rake 2.X, see the
|
|
guide for instructions for older versions):</p>
|
|
<pre>rake redmine:plugins:migrate RAILS_ENV=production</pre>
|
|
</li>
|
|
<li>
|
|
<p>Restart your Redmine instance.</p>
|
|
</li>
|
|
</ol>
|
|
<p>The Zulip plugin is now registered with Redmine!</p>
|
|
</li>
|
|
<li>
|
|
<p>On your <a href="/#settings" target="_blank">Zulip settings
|
|
page</a>, create a new Redmine bot.</p>
|
|
</li>
|
|
<li>
|
|
<p>To configure Zulip notification settings that apply to many
|
|
projects in one go, in Redmine click the "Administration" link in
|
|
the top left. Click the "Plugins" link on the Administration page,
|
|
and click the "Configure" link to the right of the Zulip plugin
|
|
description. In the "Projects" section, select all projects to which
|
|
you want these settings to apply.</p>
|
|
<p>To configure Zulip notifications for a particular Redmine project,
|
|
visit the project's Settings page.</p>
|
|
<p>
|
|
In either case, fill out the bot email address and API key, and the
|
|
Zulip stream that should receive notifications. Apply your changes.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>To test the plugin, create an issue or update an existing issue in
|
|
a Redmine project that has Zulip notifications configured (any
|
|
project, if you've configured global settings).</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p><b>Congratulations! You're done!</b><br /> When you update issues in
|
|
Redmine, the team can see these updates in real time in Zulip:</p>
|
|
|
|
<img class="screenshot" src="/static/images/integrations/redmine/001.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>
|
|
{#--------------------------------------------------------------------#}
|
|
|
|
{% 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 %}
|