{% extends "zerver/portico.html" %} {# API information page #} {% block portico_content %}
Integrations

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.

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

Services with integrations

Getting started

First, create a bot from your settings page. Look for the bot's email and API key:

The bot email address doesn't actually need to be a valid email address.

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 email us.

{#--------------------------------------------------------------------#}

Basecamp

First, create the stream you'd like to use for Basecamp notifications, and subscribe all interested parties to this stream. We recommend the name basecamp.

Next, download and install our Python bindings and example scripts on the computer you'd like to run this mirroring script from.

You will need your Basecamp account ID. You can find it as a sequence of numbers in the URL when you log in:

Edit the Basecamp and Zulip credentials in integrations/basecamp/zulip_basecamp_config.py using your favorite editor: 

BASECAMP_ACCOUNT_ID = "1234567"
BASECAMP_USERNAME = "foo@example.com"
BASECAMP_PASSWORD = "p455w0rd"

ZULIP_USER = "basecamp-bot@example.com"
ZULIP_API_KEY = "0123456789abcdef0123456789abcdef"

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

BASECAMP_INITIAL_HISTORY_HOURS = 10

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

Congratulations! You're done!
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.

^ Back to top

{#--------------------------------------------------------------------#}

Beanstalk

Zulip supports both SVN and Git notifications from Beanstalk.

First, create the stream commits and subscribe all interested parties to this stream.

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

In the URL field, enter https://bot_email:bot_api_key@api.zulip.com/v1/external/beanstalk:

Congratulations! You're done!
Whenever you do a deployment, you'll get an automated notification that looks like this:

^ Back to top

{#--------------------------------------------------------------------#}

Bitbucket

Zulip supports both Git and Mercurial notifications from Bitbucket.

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 commits if no stream is supplied in the hook; you still need to create the stream even if you are using this default.

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

In the URL field, enter https://bot_email:bot_api_key@api.zulip.com/v1/external/bitbucket:

By default, notifications are sent to the commits stream. To send notifications to a different stream, append ?stream=stream_name to the URL.

Congratulations! You're done!
Whenever you push code to your repository, you'll get an automated notification that looks like this:

^ Back to top

{#--------------------------------------------------------------------#}

Capistrano

First, download and install our Python bindings and example scripts on your Capistrano server. Once you've done that, you'll use the zulip-send utility to notify you when certain events happen.

Here's some example code for sending a Zulip notification after a deployment has completed:

after 'deploy', 'notify:humbug'

namespace :notify do
  desc "Post a message to Zulip that we've deployed"
  task :humbug do
    # this will post to Zulip as the user defined in
    # ~/.zuliprc if you omit --user and --api-key
    run_locally "echo ':beers: I just deployed to #{stage}! :beers:' | zulip-send \
    --user capistrano-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
    --stream commits --subject deployments || true"
  end
end

Some notes:

Congratulations! You're done!
Whenever you do a deployment, you'll get an automated notification that looks like this:

Thanks to Wes of TurboVote for submitting this integration!

^ Back to top

{#--------------------------------------------------------------------#}

Codebase HQ

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 codebase commits and codebase issues), make sure to subscribe all interested parties.

Next, download and install our Python bindings and example scripts on the computer you'd like to run this mirroring script from.

You will need your Codebase API Username. You can find it in the settings page of your account, under API Credentials.

Edit the Codebase and Zulip credentials in integrations/codebase/zulip_codebase_config.py using your favorite editor:

CODEBASE_API_USERNAME = "zulip-inc/leo-franchi-15"
CODEBASE_API_KEY = 0123456789abcdef0123456789abcdef

ZULIP_USER = "codebase-bot@example.com"
ZULIP_API_KEY = "0123456789abcdef0123456789abcdef"

Before your first run of the script, you may optionally choose to configure it to mirror some number of hours of prior Codebase activity:

CODEBASE_INITIAL_HISTORY_HOURS = 10

Now, simply run the api/integrations/codebase/zulip_codebase_mirror script. If needed, this script may be restarted, and it will automatically resume from when it was last running.

Congratulations! You're done!
Whenever you create a new project, commit, issue, deployment, or more, you'll get notifications in your selected streams with the associated information.

^ Back to top

{#--------------------------------------------------------------------#}

Desk.com

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 desk. Keep in mind you still need to create the stream first even if you are using this recommendation.

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

From there, click "Install Custom Action" and accept the terms. Fill in the form like this:

From here, add a new action. You'll do this for every action you want a notification on Zulip for:

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

{% verbatim %}

?stream=desk&topic={{case.id}}:+{{case.subject}}

{% endverbatim %}

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

{% verbatim %} 
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}}

You don't need to edit that. All the funny-looking stuff inside {{ and }} will be filled in by Desk.com for each event. The dialog should look like this:

{% endverbatim %}

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

Now you need to create a rule that triggers this action. Desk.com's support center has a lengthy article on rules, 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:

Finally, click Update.

Congratulations! You're done!
When a case is updated, you'll see a notification like the following, to the stream desk, with a topic that matches the case's subject name:

^ Back to top

{#--------------------------------------------------------------------#}

Email

You can send emails to Zulip! This is useful:

To send an email to a Zulip stream:

  1. visit your subscriptions page and click on the stream row to expand it.
  2. Copy the stream email address (e.g. support+abcdefg@streams.zulip.com). If the stream name contains special characters, we've transformed the name so it is a safe email recipient.
  3. 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.

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

^ Back to top

{#--------------------------------------------------------------------#}

Git

First, download and install our Python bindings and example scripts on your Git server.

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 commits if no stream is supplied in the hook; you still need to create the stream even if you are using this default.

Next, open integrations/git/zulip_git_config.py in your favorite editor, and change the following lines to specify the email address and API key for your Git bot:

ZULIP_USER = "git-bot@example.com"
ZULIP_API_KEY = "0123456789abcdef0123456789abcdef"

You can also specify which pushes will result in notifications and to what stream the notifications will be sent by modifying the commit_notice_destination function in zulip_git_config.py. By default, pushes to the master and test-post-receive branches will result in a notification to stream commits.

Save integrations/git/zulip_git_config.py to the .git/hooks directory of your git repository.

Symlink /usr/local/share/zulip/integrations/git/post-receive into the .git/hooks directory of your git repository.

Congratulations! You're done!
Whenever you make a push to the master branch of your git repository (or whatever you configured above), the Zulip git plugin will send an automated notification that looks like this:

Testing
You can test the plugin without changing your master branch by pushing to the test-post-receive branch.

^ Back to top

{#--------------------------------------------------------------------#}

GitHub

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 commits if no stream is supplied in the hook; you still need to create the stream even if you are using this default.

Next, go to your repository page and click "Settings":

From there, select "Service Hooks":

Select "Humbug" from the list, fill in the API key and email address for your bot, check the "active" checkbox, and pick "Update settings":

Congratulations! You're done!
When people push to your repository, you'll see a commit message like the following, to the stream commits with a subject that matches the repository name (in this case "humbug-test"):

^ Back to top

{#--------------------------------------------------------------------#}

Jenkins (or Hudson)

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 jenkins or hudson.

Install the plugin
Install the "Humbug" plugin by going to Manage Jenkins > Manage Plugins > Available, typing in "Humbug", and clicking "Install without restart".

Configure the plugin
Once the plugin is installed, configure it by going to Manage Jenkins > Configure System. 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).

Configure a post-build action for your project
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".

Congratulations! You're done!
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"):

Troubleshooting

^ Back to top

{#--------------------------------------------------------------------#}

JIRA

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 JIRA Plugin.

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

In your JIRA administration control panel, go to the Webhooks page. If you are using the OnDemand hosted JIRA, follow the instructions on the Atlassian wiki for locating the Webhook UI.

Give your new web hook a name, and for the URL provide the following:

https://api.zulip.com/v1/external/jira?api_key=abcdefgh&stream=jira

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

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

Congratulations! You're done!
Updates from JIRA will be sent to the Zulip stream you specified in the JIRA web-hook.

^ Back to top

{#--------------------------------------------------------------------#}

JIRA (Plugin)

If you are running JIRA version 5.2 or greater, or using the hosted JIRA provided by Atlassian, we recommend using the web-hook method above instead. This plugin supports older versions of JIRA.

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

Plugin mechanism
Next, download and install our Python bindings and example scripts.

Plugin Installation

The JIRA integration plugin requires two JIRA plugins. Please install the following plugins using the Universal Plugin Manager in your JIRA installation:

SSL Setup

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 Administration > System > Configure SSL and in the Import SSL Certificates field, enter https://api.zulip.com. After clicking Save Certificates, follow the on-screen instructions and restart JIRA for it to recognize the proper certificates.

Zulip Integration

Copy the folder integrations/jira/org/ (from the tarball you downloaded above) to your JIRA classes folder. For self-contained JIRA installations, this will be atlassian-jira/WEB-INF/classes/, but this may be different in your deployment. Edit the constants at the top of org/zulip/jira/ZulipListener.groovy and fill them with the appropriate values: 
String zulipEmail = "jira-notifications-bot@example.com"
String zulipAPIKey = "0123456789abcdef0123456789abcdef"
String zulipStream = "JIRA"
String issueBaseUrl = "https://jira.COMPANY.com/browse/"

In the Administrators page, navigate to Plugins > Other > Script Listeners. In the Add Listener section, click on the Custom Listener option. Select the events you wish the Zulip integration to fire for, and the projects you wish Zulip to be notified for. In the Name of groovy class field, enter org.zulip.jira.ZulipListener.

Click Add Listener, and JIRA will now notify your Zulip of changes to your issues!

Congratulations! You're done!
Updates from JIRA will be sent to the stream you've configured, as below.

^ Back to top

{#--------------------------------------------------------------------#}

Nagios

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 nagios if no stream is supplied in the configuration; you still need to create the stream even if you are using this default.

Next, download and install our Python bindings and example scripts on your Nagios server.

Next, open integrations/nagios/zuliprc.example in your favorite editor, and change the following lines to specify the email address and API key for your Nagios bot, saving it to /etc/nagios3/zuliprc on your Nagios server:

[api]
email=NAGIOS_BOT_EMAIL_ADDRESS
key=NAGIOS_BOT_API_KEY

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

Finally, add zulip to the members list for one or more of the contact groups in the CONTACT GROUPS section of /etc/nagios3/conf.d/contacts.cfg, doing something like: 

define contactgroup{
        contactgroup_name       admins
        alias                   Nagios Administrators
        members                 monitoring, zulip
        }
Once you've done that, reload your Nagios configuration using /etc/init.d/nagios3 reload.

Congratulations! You're done!
When your Nagios system makes an alert, you'll see a message like the following, to the stream nagios (to change this, edit the arguments to nagios-notify-zulip in /etc/nagios3/conf.d/zulip_nagios.cfg) with a subject indicating the service with an issue:

Testing
If you have external commands enabled in Nagios, you can generate a test notice from your Nagios instance by visiting using the Send custom service notification command in the Service Commands section of any individual service's page on your Nagios instance.

Troubleshooting
You can confirm whether you've correctly configured Nagios to run the Zulip plugin by looking for SERVICE NOTIFICATION lines mentioning zulip in /var/log/nagios3/nagios.log. You can confirm whether you've configured the Zulip plugin code correctly by running /usr/local/share/zulip/integrations/nagios/nagios-notify-zulip directly.

^ Back to top

{#--------------------------------------------------------------------#}

Phabricator

Zulip supports Phabricator integration and can notify you of the latest items in your Phabricator feed.

You can follow the instructions at https://github.com/zulip/phabricator-to-zulip to get it set up.

{#--------------------------------------------------------------------#}

Pivotal Tracker

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

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

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

https://api.zulip.com/v1/external/pivotal?api_key=abcdefgh&stream=pivotal

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

Congratulations! You're done!
When you make changes in Pivotal Tracker they will be reflected in Zulip:

^ Back to top

{#--------------------------------------------------------------------#}

New Relic

New Relic can send messages to a Zulip stream for alerts and deploys.

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

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

https://api.zulip.com/v1/external/newrelic?api_key=abcdefgh&stream=newrelic

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

Congratulations! You're done!
Your New Relic events will appear in Zulip:

^ Back to top

{#--------------------------------------------------------------------#}

Redmine

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.

First, create the stream you'd like to use for Redmine notifications, and subscribe all interested parties to this stream. We recommend the name redmine.

Then:

  1. Clone the Zulip Redmine plugin repository by running:

    git clone https://github.com/zulip/zulip-redmine-plugin

  2. Follow the Redmine plugin installation guide to install the zulip_redmine plugin directory, which is a subdirectory of the zulip-redmine-plugin repository directory. In a nutshell, the steps are:

    1. Copy the zulip_redmine directory to the plugins directory of your Redmine instance.

    2. Update the Redmine database by running (for Rake 2.X, see the guide for instructions for older versions):

      rake redmine:plugins:migrate RAILS_ENV=production

    3. Restart your Redmine instance.

    The Zulip plugin is now registered with Redmine!

  3. On your Zulip settings page, create a new Redmine bot.

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

    To configure Zulip notifications for a particular Redmine project, visit the project's Settings page.

    In either case, fill out the bot email address and API key, and the Zulip stream that should receive notifications. Apply your changes.

  5. 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).

Congratulations! You're done!
When you update issues in Redmine, the team can see these updates in real time in Zulip:

^ Back to top

{#--------------------------------------------------------------------#}

Subversion

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

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 commits if no stream is supplied in the hook; you still need to create the stream even if you are using this default.

Then:

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

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

^ Back to top

{#--------------------------------------------------------------------#}

Trac

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 trac if no stream is supplied in the hook; you still need to create the stream even if you are using this default.

Next, download and install our Python bindings and example scripts on your Trac server.

Next, open integrations/trac/zulip_trac_config.py 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 trac):

ZULIP_USER = "trac-notifications-bot@example.com"
ZULIP_API_KEY = "0123456789abcdef0123456789abcdef"
STREAM_FOR_NOTIFICATIONS = "trac"
TRAC_BASE_TICKET_URL = "https://trac.example.com/ticket"

Copy integrations/trac/zulip_trac.py and integrations/trac/zulip_trac_config.py into your Trac installation's plugins/ subdirectory. Once you've done that, edit your Trac installation's conf/trac.ini to add zulip_trac to the [components] section, as follows:

[components]
zulip_trac = enabled

You may then need to restart Trac (or Apache) so that Trac will load our plugin.

Congratulations! You're done!
When people open new tickets (or edit existing tickets), you'll see a message like the following, to the stream trac (or whatever you configured above) with a subject that matches the ticket name:

Additional trac configuration
After using the plugin for a while, you may want to customize which changes to tickets result in a Zulip notification using the TRAC_NOTIFY_FIELDS setting in zulip_trac_config.py.

^ Back to top

{#--------------------------------------------------------------------#}

Trello

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

Next, download a copy of trello-to-zulip and follow the instructions in README.md. When you make changes in Trello, they will be reflected in Zulip:

Thanks to Nathan from FoundationDB for submitting this integration!

^ Back to top

{#--------------------------------------------------------------------#} {% endblock %} {% block customhead %} {{ block.super }} {% endblock %}