diff --git a/zulip/integrations/bridge_with_irc/doc.md b/zulip/integrations/bridge_with_irc/doc.md new file mode 100644 index 0000000000..e204754de8 --- /dev/null +++ b/zulip/integrations/bridge_with_irc/doc.md @@ -0,0 +1,67 @@ +Mirror an IRC channel in Zulip! + +### Install the bridge software + +1. Clone the Zulip API repository, and install its dependencies. + + ``` + git clone https://github.com/zulip/python-zulip-api.git + cd python-zulip-api + python3 ./tools/provision + ``` + + This will create a new Python virtualenv. You'll run the bridge service + inside this virtualenv. + +1. Activate the virtualenv by running the `source` command printed + at the end of the output of the previous step. + +1. Go to the directory containing the bridge script if you haven't already done so + + ``` + cd zulip/integrations/bridge_with_irc + ``` + +1. Install the bridge dependencies in your virtualenv, by running: + + ``` + pip install -r requirements.txt + ``` + +### Configure the bridge + +1. {!create-a-generic-bot.md!} + Download the bot's `zuliprc` configuration file to your computer. + +1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip + stream that will contain the mirror. + +1. Inside the virtualenv you created above, run: + + ``` + python irc-mirror.py --irc-server=IRC_SERVER --channel= --nick-prefix= \ + --stream= [--topic=] \ + --site= --user= \ + --api-key= + ``` + + `--topic` is a Zulip topic, is optionally specified, defaults to "IRC". + +Example command: + +``` +./irc-mirror.py --irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \ +--stream='test here' --topic='#mypy' \ +--site="https://chat.zulip.org" --user=bot@email.com \ +--api-key=DeaDbEEf +``` + +**Congratulations! You're done!** + +Your Zulip messages may look like: + +![IRC message on Zulip](/static/images/integrations/irc/001.png) + +Your IRC messages may look like: + +![Zulip message on IRC](/static/images/integrations/irc/002.png) diff --git a/zulip/integrations/bridge_with_matrix/doc.md b/zulip/integrations/bridge_with_matrix/doc.md new file mode 100644 index 0000000000..57dd395617 --- /dev/null +++ b/zulip/integrations/bridge_with_matrix/doc.md @@ -0,0 +1,95 @@ +Exchange messages between [matrix.org](https://matrix.org) and Zulip! If +you're looking to mirror an IRC channel in particular, we recommend our +[direct IRC integration](/integrations/doc/irc). + +### Install the bridge software + +1. Clone the Zulip API repository, and install its dependencies. + + ``` + git clone https://github.com/zulip/python-zulip-api.git + cd python-zulip-api + python3 ./tools/provision + ``` + + This will create a new Python virtualenv. You'll run the bridge service + inside this virtualenv. + +1. Activate the virtualenv by running the `source` command printed + at the end of the output of the previous step. + +1. Install the Matrix bridge software in your virtualenv, by running: + + ``` + pip install -r zulip/integrations/bridge_with_matrix/requirements.txt + ``` + +### Configure the bridge + +1. {!create-a-generic-bot.md!} + Download the bot's `zuliprc` configuration file to your computer. + +1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip + stream that will contain the mirror. + +1. Inside the virtualenv you created above, run + + ``` + python zulip/integrations/bridge_with_matrix/matrix_bridge.py \ + --write-sample-config matrix_bridge.conf --from-zuliprc + ``` + + where `` is the path to the `zuliprc` file you downloaded. + +1. Create a user on [matrix.org](https://matrix.org/) or another matrix + server, preferably with a descriptive name like `zulip-bot`. + +1. Edit `matrix_bridge.conf` to look like this: + + ``` + [zulip] + email = bridge-bot@chat.zulip.org + api_key = aPiKeY + site = https://chat.zulip.org + stream = "stream name" + topic = "{{ integration_display_name }} mirror" + [matrix] + host = https://matrix.org + username = + password = + room_id = #room:matrix.org + ``` + + The first three values should already be there; the rest you'll have to fill in. + Make sure **stream** is set to the stream the bot is + subscribed to. + + {% if 'IRC' in integration_display_name %} + + NOTE: For matrix.org, the `room_id` generally takes the form + `#_#:matrix.org`. You can see the format for + several popular IRC networks + [here](https://github.com/matrix-org/matrix-appservice-irc/wiki/Bridged-IRC-networks), under + the "Room alias format" column. + + For example, the `room_id` for the `#zulip-test` channel on freenode is + `#freenode_#zulip-test:matrix.org`. + + {% endif %} + +1. Run the following command to start the matrix bridge: + + ``` + python zulip/integrations/bridge_with_matrix/matrix_bridge.py -c matrix_bridge.conf + ``` + +!!! tip "" + + You can customize the message formatting by + editing the variables `MATRIX_MESSAGE_TEMPLATE` and `ZULIP_MESSAGE_TEMPLATE` + in `zulip/integrations/bridge_with_matrix/matrix_bridge.py`. + +**Note**: There are a handful of +[IRC channels](https://github.com/matrix-org/matrix-appservice-irc/wiki/Channels-from-which-the-IRC-bridge-is-banned) +that have temporarily banned the Matrix.org IRC bridge. +You can't currently mirror those channels using this integration. diff --git a/zulip/integrations/codebase/doc.md b/zulip/integrations/codebase/doc.md new file mode 100644 index 0000000000..ce42f2c508 --- /dev/null +++ b/zulip/integrations/codebase/doc.md @@ -0,0 +1,53 @@ +# Zulip Codebase integration + +Get Codebase notifications in Zulip! + +{start_tabs} + +1. [Create the channels](/help/create-a-channel) you’d like to use for + Codebase notifications. There will be two types of notification + messages: issue-related and commit-related. + +1. {!create-an-incoming-webhook.md!} + +1. {!download-python-bindings.md!} + +1. Install the requirements for the integration script with: + + `pip install /usr/local/share/zulip/integrations/codebase/requirements.txt` + +1. {!change-zulip-config-file.md!} + + Also add `ZULIP_TICKETS_STREAM_NAME` and `ZULIP_COMMITS_STREAM_NAME` + with the names of the channels you created in step 1. + +1. Go to your Codebase settings, and click on **My Profile**. Under + **API Credentials**, you will find your API key and username. + Edit the following lines in `zulip_codebase_config.py` to add your + Codebase credentials: + + ``` + CODEBASE_API_USERNAME = "zulip-inc/user-name-123" + CODEBASE_API_KEY = 0123456789abcdef0123456789abcdef + ``` + + !!! tip "" + + Before your first run of the script, you may also want to configure + the integration to mirror some number of hours of prior Codebase + activity, e.g., `CODEBASE_INITIAL_HISTORY_HOURS = 10`. + +1. Run the + `/usr/local/share/zulip/integrations/codebase/zulip_codebase_mirror` + script. + + !!! tip "" + + This script can be restarted, and it will resume from when it was + last running. + +{end_tabs} + +{!congrats.md!} + +![Codebase bot message](/static/images/integrations/codebase/001.png) diff --git a/zulip/integrations/git/doc.md b/zulip/integrations/git/doc.md new file mode 100644 index 0000000000..ffd281f0a7 --- /dev/null +++ b/zulip/integrations/git/doc.md @@ -0,0 +1,31 @@ +Get Zulip notifications for your Git repositories! + +1. {!create-an-incoming-webhook.md!} + +1. {!download-python-bindings.md!} + +1. {!create-channel.md!} + +1. {!change-zulip-config-file.md!} + + You may also need to change the value of `STREAM_NAME`. + + You can specify the branches that will be used for notifications by modifying + the `commit_notice_destination` function. By default, + pushes to the `main`, `master`, and `test-post-receive` branches will result in a + notification. + +1. Symlink `/usr/local/share/zulip/integrations/git/zulip_git_config.py` + to the `.git/hooks` directory of your Git repository. + +1. Symlink `/usr/local/share/zulip/integrations/git/post-receive` + to the `.git/hooks` directory of your Git repository. + +!!! tip "" + + You can test the plugin without changing your `main` branch by + pushing to the `test-post-receive` branch. + +{!congrats.md!} + +![Git bot message](/static/images/integrations/git/001.png) diff --git a/zulip/integrations/google/doc.md b/zulip/integrations/google/doc.md new file mode 100644 index 0000000000..e9a21b3afb --- /dev/null +++ b/zulip/integrations/google/doc.md @@ -0,0 +1,72 @@ +Get Google Calendar reminders in Zulip! This is a great way to see +your reminders directly in your Zulip feed. + +1. {!download-python-bindings.md!} + + This bot should be set up on a trusted machine, because your API + key is visible to local users through the command line or config + file. + +1. Next, follow the instructions for **Step 1** at + [this link](https://developers.google.com/google-apps/calendar/quickstart/python) + to get a `client_secret` file. Save this file as `client_secret.json` + to your `~/` directory. + +1. Next, install the latest Google API Client for Python by following the + instructions on the + [Google website](https://developers.google.com/api-client-library/python/start/installation). + +1. In Zulip, go to your click on the cog in the top right corner, and + then clicking on **Personal settings**. + +1. Click on the tab that’s labeled **Account & privacy** and click on + **Manage your API key**. Enter your password if prompted, and + download the `zuliprc` file. Save this file as `.zuliprc` to your `~/` + directory. + + ![Download zuliprc file](/static/images/integrations/google/calendar/001.png) + +1. Run the `get-google-credentials` with this command: + + python /usr/local/share/zulip/integrations/google/get-google-credentials + +1. It should open up a browser and ask you for certain permissions. Give + Zulip access, and move on to the next step. If it doesn’t open a + browser, follow the instructions in the terminal window. + +1. Now, all that’s left to do is to run the `gcal-bot` script, in the + same directory as the `get-google-credentials` script, with the + necessary parameters: + + python /usr/local/share/zulip/integrations/google/gcal-bot --user foo@zulip.com + + The `--user` flag specifies the user to send the reminder to. + +1. Don’t close the terminal window with the bot running (you can use + `screen` if needed). You will only get reminders if the bot is still + running. + +{!congrats.md!} + +![Calendar demo](/static/images/integrations/google/calendar/003.png) + +## Supported parameters + +There are two optional flags that you can specify when running this +script: + +* `--calendar`: This flag specifies the calendar to watch from the + user’s Google account. By default, this flag is set to a user’s + primary or default calendar. To specify a calendar, you need the + calendar ID which can be obtained by going to Google Calendar and + clicking on the wedge next to the calendar’s name. Click on settings + in **Calendar settings** in the drop down, and look for the **Calendar + Address** section. Copy the **Calendar ID** from the right side of the + page and use that as the value for this flag. + +![Specify a calendar](/static/images/integrations/google/calendar/002.png) + +* `--interval`: This flag specifies the interval of time - in + minutes - between receiving the reminder, and the actual event. For + example, an interval of 30 minutes would mean that you would receive a + reminder for an event 30 minutes before it is scheduled to occur. diff --git a/zulip/integrations/hg/doc.md b/zulip/integrations/hg/doc.md new file mode 100644 index 0000000000..569a4c5f03 --- /dev/null +++ b/zulip/integrations/hg/doc.md @@ -0,0 +1,86 @@ +Get Zulip notifications when you `hg push`! + +1. {!create-channel.md!} + +1. {!create-an-incoming-webhook.md!} + +1. {!download-python-bindings.md!} + +1. Edit the `hg/.hgrc` configuration file for this default Mercurial +repository and add the following sections, using the credentials for +your Mercurial bot and setting the appropriate path to the integration +hook if it installs in a different location on this system: + + [hooks] + changegroup = python:zulip_changegroup.hook + + [zulip] + email = "hg-bot@example.com" + api_key = "0123456789abcdefg" + stream = "commits" + site = {{ api_url }} + +1. Add the directory where the `zulip_changegroup.py` script was +installed to the environment variable `PYTHONPATH`. For example, if +you installed the Zulip Python bindings at the system level, it'd be: + + export PYTHONPATH=/usr/local/share/zulip/integrations/hg:$PYTHONPATH + +That’s all it takes for the basic setup! On the next `hg push`, you’ll +get a Zulip update for the changeset. + +### More configuration options + +The Mercurial integration also supports: + +- linking to changelog and revision URLs for your repository’s web UI +- branch whitelists and blacklists + +#### Web repository links + +If you’ve set up your repository to be [browsable via the web][1], +add a `web_url` configuration option to the `zulip` section of your +default `.hg/hgrc` to get changelog and revision links in your Zulip +notifications: + + [zulip] + email = "hg-bot@example.com" + api_key = "0123456789abcdefg" + stream = "commits" + web_url = "http://hg.example.com:8000/" + site = {{ api_url }} + +[1]: https://www.mercurial-scm.org/wiki/QuickStart#Network_support + +#### Branch whitelists and blacklists + +By default, this integration will send Zulip notifications for +changegroup events for all branches. If you’d prefer to only receive +Zulip notifications for specified branches, add a `branches` +configuration option to the `zulip` section of your default `.hg/hgrc`, +containing a comma-separated list of the branches that should produce +notifications: + + [zulip] + email = "hg-bot@example.com" + api_key = "0123456789abcdefg" + stream = "commits" + branches = "prod,default" + +You can also exclude branches that you don’t want to cause +notifications. To do so, add an `ignore_branches` configuration option +to the `zulip` section of your default `.hg/hgrc`, containing a +comma-separated list of the branches that should be ignored: + + [zulip] + email = "hg-bot@example.com" + api_key = "0123456789abcdefg" + stream = "commits" + ignore_branches = "noisy,even-more-noisy" + +When team members push new changesets with `hg push`, you’ll get a +Zulip notification. + +{!congrats.md!} + +![Mercurial bot message](/static/images/integrations/hg/001.png) diff --git a/zulip/integrations/jira/doc.md b/zulip/integrations/jira/doc.md new file mode 100644 index 0000000000..cd11876fed --- /dev/null +++ b/zulip/integrations/jira/doc.md @@ -0,0 +1,71 @@ +*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](./jira) above instead. This plugin supports older +versions of Jira.* + +{!create-channel.md!} + +### Plugin mechanism + +{!download-python-bindings.md!} + +#### Plugin installation + +The Jira integration plugin requires two Jira plugins. Please install +the following plugins using the **Universal Plugin Manager** in your +Jira installation: + +* [Script Runner Plugin][script-runner] +* [SSL Plugin][ssl-plugin] + +[script-runner]: https://marketplace.atlassian.com/plugins/com.onresolve.jira.groovy.groovyrunner +[ssl-plugin]: https://marketplace.atlassian.com/plugins/com.atlassian.jira.plugin.jirasslplugin + +#### 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. + +1. Navigate to **Administration > System > Configure SSL** and in the + **Import SSL Certificates** field, enter `{{ api_url }}`. + +2. After clicking **Save Certificates**, follow the on-screen + instructions and restart Jira for it to recognize the proper + certificates. + +#### Zulip integration + +1. 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. + +2. Edit the constants at the top of + `org/zulip/jira/ZulipListener.groovy` and fill them with the + appropriate values: + +``` Python +String zulipEmail = "jira-notifications-bot@example.com" +String zulipAPIKey = "0123456789abcdef0123456789abcdef" +String zulipStream = "jira" +String issueBaseUrl = "https://jira.COMPANY.com/browse/" +``` + +3. On the **Administrators** page, navigate to + **Plugins > Other > Script Listeners**. + +4. 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. + +5. In the **Name of groovy class** field, enter + `org.zulip.jira.ZulipListener`. + +6. Click **Add Listener**, and Jira will now notify your Zulip of + changes to your issues! Updates from Jira will be sent to the stream + you've configured. + +{!congrats.md!} + +![Jira bot message](/static/images/integrations/jira/001.png) diff --git a/zulip/integrations/nagios/doc.md b/zulip/integrations/nagios/doc.md new file mode 100644 index 0000000000..c0f342a6f5 --- /dev/null +++ b/zulip/integrations/nagios/doc.md @@ -0,0 +1,63 @@ +1. {!create-channel.md!} + +1. {!download-python-bindings.md!} + +1. {!create-an-incoming-webhook.md!} + +1. 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/nagios4/zuliprc` + on your Nagios server: + + ``` + [api] + email = NAGIOS_BOT_EMAIL_ADDRESS + key = NAGIOS_BOT_API_KEY + site = {{ api_url }} + ``` + +1. Copy `integrations/nagios/zulip_nagios.cfg` to `/etc/nagios4/conf.d` + on your Nagios server. + +1. Finally, add `zulip` to the `members` list for one or more of the + contact groups in the `CONTACT GROUPS` section of + `/etc/nagios4/conf.d/contacts.cfg`, doing something like: + + ``` + define contactgroup { + contactgroup_name admins + alias Nagios Administrators + members monitoring, zulip + } + ``` + +1. Once you’ve done that, reload your Nagios configuration using + `/etc/init.d/nagios4 reload`. + +1. 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/nagios4/conf.d/zulip_nagios.cfg`) + with a topic indicating the service with an issue. + +{!congrats.md!} + +![Nagios bot message](/static/images/integrations/nagios/001.png) + +### Testing + +If you have [external commands enabled in Nagios][1], +you can generate a test notice from your Nagios instance by +using the `Send custom service notification` command in the +`Service Commands` section of any individual service’s page +on your Nagios instance. + +[1]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/extcommands.html + +### 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/nagios4/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. diff --git a/zulip/integrations/openshift/doc.md b/zulip/integrations/openshift/doc.md new file mode 100644 index 0000000000..7a7a2a8df1 --- /dev/null +++ b/zulip/integrations/openshift/doc.md @@ -0,0 +1,43 @@ +This integration sends a notification every time a deployment is made +in an OpenShift instance. + +1. {!create-channel.md!} + +1. {!download-python-bindings.md!} + +1. Then, create a new commit including all the changes made to the + repository, and push it to your app. + +1. After that, connect to the application through SSH. If you don’t know + how to do this, log in to your OpenShift Online account, go to your + application’s dashboard, and click **Want to log in to your + application?**. There you’ll find the app’s SSH user, address, and + further information on SSH, in case you need it. + + ![Connecting to application](/static/images/integrations/openshift/002.png) + +1. {!change-zulip-config-file.md!} + +1. You can also specify which pushes will result in notifications and to + what stream the notifications will be sent by modifying the + `deployment_notice_destination` function in + `zulip_openshift_config.py`. By default, deployments triggered by + commits pushed to the `main`, `master`, and `test-post-receive` branches will + result in a notification to stream `deployments`. + +1. Save the file, and symlink + `$OPENSHIFT_PYTHON_DIR/virtenv/share/zulip/integrations/openshift/post-receive` + into the `~/app-root/repo/.openshift/action_hooks` directory. + +1. Whenever you make a push to the `main` branch of your application’s + repository (or whichever branch you configured above), or if you force + a deployment, the Zulip OpenShift plugin will send an automated + notification. + +{!congrats.md!} + +![OpenShift integration message](/static/images/integrations/openshift/001.png) + +### Testing + +You can test the plugin without changing your `main` branch by pushing to the `test-post-receive` branch. diff --git a/zulip/integrations/perforce/doc.md b/zulip/integrations/perforce/doc.md new file mode 100644 index 0000000000..d4ae2c1f54 --- /dev/null +++ b/zulip/integrations/perforce/doc.md @@ -0,0 +1,48 @@ +Zulip supports integration with Perforce as a [trigger][1] +that fires once a changelist is submitted and committed. + +[1]: https://www.perforce.com/manuals/p4sag/Content/P4SAG/chapter.scripting.html + +1. {!download-python-bindings.md!} + +1. The Perforce trigger will be installed to a location like + `/usr/local/share/zulip/integrations/perforce`. + +1. {!change-zulip-config-file.md!} + +1. If you have a P4Web viewer set up, you may change `P4_WEB` + to point at the base URL of the server. If this is configured, + then the changelist number of each commit will be converted to + a hyperlink that displays the commit details on P4Web. + +1. Edit your [trigger table][2] with `p4 triggers` and add an entry + something like the following: + + notify_zulip change-commit //depot/... "/usr/local/share/zulip/integrations/perforce/zulip_change-commit.py %change% %changeroot%" + + [2]: https://www.perforce.com/manuals/p4sag/Content/P4SAG/chapter.scripting.html#d0e14583 + +1. By default, this hook will send to streams of the form + `depot_subdirectory-commits`. So, a changelist that modifies + files in `//depot/foo/bar/baz` will result in a message to + stream `foo-commits`. Messages about changelists that modify + files in the depot root or files in multiple direct subdirectories + of the depot root will be sent to `depot-commits`. + If you'd prefer different behavior, such as all commits across your + depot going to one stream, change it now in `zulip_perforce_config.py`. + Make sure that everyone interested in getting these post-commit Zulips + is subscribed to the relevant streams! + +1. By default, this hook will send a message to Zulip even if the + destination stream does not yet exist. Messages to nonexistent + streams prompt the Zulip Notification Bot to inform the bot's + owner by direct message that they may wish to create the stream. + If this behaviour is undesirable, for example with a large and busy + Perforce server, change the `ZULIP_IGNORE_MISSING_STREAM` + variable in `zulip_perforce_config.py` to `True`. + This will change the hook's behaviour to first check whether the + destination stream exists and silently drop messages if it does not. + +{!congrats.md!} + +![Perforce notification bot message](/static/images/integrations/perforce/001.png) diff --git a/zulip/integrations/rss/doc.md b/zulip/integrations/rss/doc.md new file mode 100644 index 0000000000..967d942f56 --- /dev/null +++ b/zulip/integrations/rss/doc.md @@ -0,0 +1,26 @@ +Get service alerts, news, and new blog posts right in Zulip with our +RSS integration! + +!!! tip "" + + Note that [the Zapier integration][1] is usually a simpler way to + integrate RSS with Zulip. + +[1]: ./zapier + +1. {!create-channel.md!} + +1. {!create-an-incoming-webhook.md!} + +1. {!download-python-bindings.md!} + +1. The RSS integration will be installed to a location like + `/usr/local/share/zulip/integrations/rss/rss-bot`. + +1. Follow the instructions in the `rss-bot` script for configuring the + bot, adding your subscriptions, and setting up a cron job to run + the bot. + +{!congrats.md!} + +![RSS bot message](/static/images/integrations/rss/001.png) diff --git a/zulip/integrations/svn/doc.md b/zulip/integrations/svn/doc.md new file mode 100644 index 0000000000..e4e3fbcae1 --- /dev/null +++ b/zulip/integrations/svn/doc.md @@ -0,0 +1,27 @@ +It is easy to send Zulips on SVN commits, by configuring a +post-commit hook. To do this: + +1. {!create-channel.md!} + +1. {!download-python-bindings.md!} + +1. Install `pysvn`. On Linux, you can install the `python-svn` + package. On other platforms, you can install a binary or from + source by following the [instructions on the pysvn website][1]. + + [1]: http://pysvn.tigris.org/project_downloads.html + +1. {!change-zulip-config-file.md!} + +1. 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. + +1. 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! + +{!congrats.md!} + +![SVN commit bot message](/static/images/integrations/svn/001.png) diff --git a/zulip/integrations/trac/doc.md b/zulip/integrations/trac/doc.md new file mode 100644 index 0000000000..165f328346 --- /dev/null +++ b/zulip/integrations/trac/doc.md @@ -0,0 +1,43 @@ +1. {!create-channel.md!} + +1. {!download-python-bindings.md!} + +1. {!change-zulip-config-file.md!} + +1. Also, change the following lines: + + ``` + STREAM_FOR_NOTIFICATIONS = "trac" + TRAC_BASE_TICKET_URL = "https://trac.example.com/ticket" + ``` + +1. Set `STREAM_FOR_NOTIFICATIONS` to the name of the stream + you'd like the notifications to be sent to. + +1. 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 + ``` + +1. You may then need to restart Trac (or Apache) so that Trac will load + our plugin. + +1. When people open new tickets (or edit existing tickets), notifications + will be sent to the stream `trac` (or whatever you + configured above) with a topic that matches the ticket name. + +{!congrats.md!} + +![Trac bot message](/static/images/integrations/trac/001.png) + +### 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`. diff --git a/zulip/integrations/twitter/doc.md b/zulip/integrations/twitter/doc.md new file mode 100644 index 0000000000..622b0beb64 --- /dev/null +++ b/zulip/integrations/twitter/doc.md @@ -0,0 +1,82 @@ +Fetch tweets from Twitter in Zulip! This is great for seeing and +discussing who is talking about you, friends, competitors, or +important topics in real time. + +1. {!create-channel.md!} + +1. {!create-an-incoming-webhook.md!} + + The API keys for "Incoming webhook" bots are limited to only + sending messages via webhooks. Thus, this bot type lessens + the security risks associated with exposing the bot's API + key to third-party services. + +1. Download your new bot's `zuliprc` configuration file. + +1. {!download-python-bindings.md!} + +1. The Twitter bot should be set up on a trusted machine, because your API + key is visible to local users through the command line or config + file. + +1. Next, install **version 1.0 or later** of the `python-twitter` + library. If your operating system distribution doesn’t package a new + enough version, you can install the library from source from + [the GitHub repository](https://github.com/bear/python-twitter). + +1. Next, set up Twitter authentication. This bot uses OAuth to + authenticate with Twitter, and in order to obtain a consumer key & + secret, you must register a new application under your Twitter + account: + +1. Log in to . + +1. Click on `Create New App` and fill out the form. + +1. Click on the application you created and click **create my access + token**. Fill in the requested values. + +1. Create a `~/.zulip_twitterrc` with the following contents: + + ``` + [twitter] + consumer_key = + consumer_secret = + access_token_key = + access_token_secret = + ``` + +1. Place your bot's `zuliprc` in a directory of your choice (for the next step, + `~/zuliprc` is used). + +1. Test the script by running it manually: + + /usr/local/share/zulip/integrations/twitter/twitter-bot --search="@nprnews,quantum + physics" --config-file=~/zuliprc + + /usr/local/share/zulip/integrations/twitter/twitter-bot --twitter-name="<@your- + twitter-handle>" --config-file=~/zuliprc + + Note: `twitter-bot` may install to a different location on + your operating system distribution. + +1. Configure a crontab entry for this script. A sample crontab entry + that will process tweets every minute is: + + ``` + * * * * * /usr/local/share/zulip/integrations/twitter/twitter-bot --search="@nprnews, + quantum physics" --config-file=~/zuliprc + ``` + +1. When someone tweets a message containing one of your search terms, + get a Zulip on your specified stream, with the search term as + the topic. + +{!congrats.md!} + +![Twitter bot message](/static/images/integrations/twitter/001.png) + +Note that the Twitter search bot integration **just sends links to +tweets**; the pretty inline previews of tweets are generated by the +Twitter card rendering integration configured in +`/etc/zulip/settings.py` on the Zulip server.