Import from Gitter (beta)
You can import your current workspace into a Zulip organization. It's a great way
to preserve your workspace history when you migrate to Zulip, and to
make the transition easy for the members of your organization.
The import will include your organization's:
- Name
- Message history, including attachments and emoji reactions
- Users, including names and avatars
- Channels, including all user subscriptions
Import process overview
To import your Gitter organization into Zulip, you will need to take the
following steps, which are described in more detail below:
- Instructions for all platforms
Import your organization from Gitter into Zulip
Export your Gitter data
Gitter's data export tool allows you
to export all public channel messages.
- Instructions for all platforms
-
Export your Gitter data. You will receive .json files of the public
rooms that you are a part of.
-
Select the gitter_data.json file of the room which you want to
import into Zulip.
Note: You will need a Gitter API token to export data. You can get this
token by following the instructions in the Getting Started section of
the Gitter documentation.
Import your data into Zulip
To start using Zulip, you will need to choose between Zulip Cloud and
self-hosting Zulip. For a simple managed solution, with no setup or maintenance
overhead, you can sign up for Zulip Cloud with just a few clicks.
Alternatively, you can self-host your Zulip organization. See
here to learn more.
You can only import a workspace as a new Zulip organization. Your imported
message history cannot be added into an existing Zulip organization.
Import into a Zulip Cloud organization
If you are using Zulip Cloud, we'll take it from here! Please e-mail
[email protected] with the following information:
-
The subdomain you would like to use for your organization. Your Zulip chat will
be hosted at <subdomain>.zulipchat.com.
-
The exported data file containing your workspace message history export.
-
The username that will have the owner role
in your Zulip organization.
If the organization already exists, the import process will overwrite all
data that's already there. If needed, we're happy to preserve your
data by moving an organization you've already created to a new
subdomain prior to running the import process.
Import into a self-hosted Zulip server
Zulip's import tools are robust, and have been used to import workspaces
with 10,000 members and millions of messages. If you're planning on doing
an import much larger than that, or run into performance issues when
importing, contact us for help.
-
Follow steps
1
and
2
of the guide for installing a new Zulip
server.
-
Copy the exported data file containing your workspace message
history export onto your Zulip server, and put it in /tmp/.
-
Log in to a shell on your Zulip server as the zulip user.
-
To import into an organization hosted on the root domain
(EXTERNAL_HOST) of the Zulip installation, run the following
commands.
-
The import could take several minutes to run,
depending on how much data you're importing.
-
The server stop/restart commands are only
necessary when importing on a server with minimal
RAM, where an OOM kill might otherwise occur.
cd /home/zulip/deployments/current
./scripts/stop-server
./manage.py convert_gitter_data /tmp/gitter_data.json --output /tmp/converted_gitter_data
./manage.py import '' /tmp/converted_gitter_data
./scripts/start-server
Alternatively, to import into a custom subdomain, run:
cd /home/zulip/deployments/current
./scripts/stop-server
./manage.py convert_gitter_data /tmp/gitter_data.json --output /tmp/converted_gitter_data
./manage.py import <subdomain> /tmp/converted_gitter_data
./scripts/start-server
-
Follow step 4
of the guide for installing a new Zulip
server.
Import details
Whether you are using Zulip Cloud or self-hosting Zulip, here are a few notes to
keep in mind about the import process:
-
Gitter's export tool does not export
workspace settings, so you will need to configure the settings for your Zulip
organization. This includes settings
like email visibility,
message editing permissions,
and how users can join your organization.
-
Gitter's export tool does not export user settings, so users in your organization
may want to customize their account settings.
-
The Gitter API doesn't contain data on which users are
administrators of a Gitter channel. As a result, all Gitter users are imported
into Zulip as members.
-
Gitter's export tool doesn't export email addresses, only GitHub usernames.
Zulip's import tool will set GitHub as the only authentication method enabled
by default to avoid user confusion.
-
You can merge multiple Gitter channels into a single Zulip
organization using this
tool.
-
Zulip's import tool doesn't translate Gitter's Markdown format into Zulip's
Markdown format (there are a few corner cases where the syntax is different).
Additionally, Gitter's issue mention syntax isn't translated.
-
Message edit history is not imported.
Get your organization started with Zulip
Once the import process is completed, you will need to:
- Instructions for all platforms
How users will log in for the first time
When you create your organization, users will immediately be able to log in
without a password using GitHub as the authentication method
. Once they log
in, users whose accounts have been imported will need to change their Zulip
email address in order to receive email
notifications.
A user's email notifications will not work until they update the email
associated with their Zulip account.
When user accounts are imported, users initially do not have passwords
configured. Users can reset their own passwords by
following the instructions on your Zulip organization's login page.
For security reasons, passwords are never exported.
Related articles