Skip to content

Update the doc of the IRC bridge integration. #870

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update the doc of the IRC bridge integration. #870

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 55 additions & 43 deletions zulip/integrations/bridge_with_irc/doc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,67 +1,79 @@
Mirror an IRC channel in Zulip!
# Zulip IRC Integration

### Install the bridge software
Mirror messages between an IRC channel and a Zulip channel in real-time!

1. Clone the Zulip API repository, and install its dependencies.
{start_tabs}

```
git clone https://github.com/zulip/python-zulip-api.git
cd python-zulip-api
python3 ./tools/provision
```
1. {!download-python-bindings.md!}

1. {!install-requirements.md!}

1. Register a nick that ends with the suffix `_zulip` on your IRC server.

This will create a new Python virtualenv. You'll run the bridge service
inside this virtualenv.
1. {!create-a-generic-bot.md!}

1. Activate the virtualenv by running the `source` command printed
at the end of the output of the previous step.
1. Download the `zuliprc` configuration file of your bot by clicking the
download (<i class="fa fa-download"></i>) icon under the bot's name, and
save to `~/.zuliprc`.

1. Go to the directory containing the bridge script if you haven't already done so
1. [Subscribe the bot][subscribe-channels] to the Zulip channel where IRC
messages should be mirrored.

1. Begin mirroring messages between the IRC channel and the Zulip channel
by running the `irc-mirror.py` script with the
[required command-line arguments](#required-arguments). Use the
[optional arguments](#optional-arguments) to configure the mirroring
behavior.

Here's an example command that mirrors messages between the
**#python-mypy** channel on the `irc.freenode.net` server and the "mypy"
topic on the **#irc-discussions** channel on Zulip:

```
cd zulip/integrations/bridge_with_irc
python {{ integration_path }}/irc-mirror.py \
--irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is integration_path the right path to find this file after doing a pip install?

--stream='irc-discussions' --topic='mypy'
```

1. Install the bridge dependencies in your virtualenv, by running:
1. Messages will be mirrored only when the terminal session with the bot
remains open. Consider using `screen` to run the bot in the background.
You can restart the integration at any time by re-running the
`irc-mirror.py` script.

Copy link
Member

@timabbott timabbott Jul 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

screen is a weird way to do it. We should suggest supervisor as a tool intended for keeping a job running.

We use it in the botserver (And zulip/zulip server), if you aren't familiar with it.

{end_tabs}

You're done! Messages in your Zulip channel may look like:

```
pip install -r requirements.txt
```
![IRC message on Zulip](/static/images/integrations/irc/001.png)

### Configure the bridge
Messages in your IRC channel may look like:

1. {!create-a-generic-bot.md!}
Download the bot's `zuliprc` configuration file to your computer.
![Zulip message on IRC](/static/images/integrations/irc/002.png)

1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip
stream that will contain the mirror.
[subscribe-channels]: /help/manage-user-channel-subscriptions#subscribe-a-user-to-a-channel

1. Inside the virtualenv you created above, run:
### Configuration options

```
python irc-mirror.py --irc-server=IRC_SERVER --channel=<CHANNEL> --nick-prefix=<NICK> \
--stream=<STREAM> [--topic=<TOPIC>] \
--site=<zulip.site> --user=<bot-email> \
--api-key=<api-key>
```
The integration script accepts the following command-line arguments:

`--topic` is a Zulip topic, is optionally specified, defaults to "IRC".
#### Required arguments

Example command:
- `--irc-server`: The IRC server to mirror.

```
./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" [email protected] \
--api-key=DeaDbEEf
```
- `--nick-prefix`: Your registered IRC nick without the `_zulip` suffix.

**Congratulations! You're done!**
- `--channel`: The IRC channel to mirror.

Your Zulip messages may look like:
- `--stream`: The name of the Zulip channel you want to mirror. The default
channel name is **#general**.

![IRC message on Zulip](/static/images/integrations/irc/001.png)
#### Optional arguments

Your IRC messages may look like:
- `--topic`: The name of the Zulip topic you want to receive and send
messages in. The default topic name is "IRC".

![Zulip message on IRC](/static/images/integrations/irc/002.png)
- `--port`: The port to connect to the IRC server on. Defaults to 6667.

- `--nickserv-pw`: Password corresponding to the IRC nick.

- `--sasl-password`: Password for SASL authentication.
Loading