zulip/help/import-from-gitter.md

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:

{start_tabs}

1. Export your Gitter data.

2. Import your Gitter data into Zulip.

3. Get your organization started with Zulip!

{end_tabs}

Import your organization from Gitter into Zulip

Export your Gitter data

Gitter's data export tool allows you to export all public channel messages.

{start_tabs}

1. Export your Gitter data. You will receive .json files of the public rooms that you are a part of.

2. Select the gitter_data.json file of the room which you want to import into Zulip.

!!! warn ""

**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](https://developer.gitter.im/docs/).

{end_tabs}

Import your data into Zulip

{!import-your-data-into-zulip.md!}

{start_tabs}

{tab|zulip-cloud}

{!import-into-a-zulip-cloud-organization.md!}

1. The username that will have the owner role in your Zulip organization.

{!import-zulip-cloud-organization-warning.md!}

{tab|self-hosting}

{!import-into-a-self-hosted-zulip-server.md!}

1. To import into an organization hosted on the root domain (EXTERNAL_HOST) of the Zulip installation, run the following commands.

   {!import-self-hosted-server-tips.md!}

   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
   

2. Follow step 4 of the guide for installing a new Zulip server.

{end_tabs}

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:

{start_tabs}

1. Configure the settings for your organization, which are not exported. This includes settings like email visibility, message editing permissions, and how users can join your organization.

2. Configure user roles. Only organization owners and administrators can do this.

   • If you import into Zulip Cloud, you will specify the user whose account will have the owner role when you request the import.
   • If you self-host, you can follow the Zulip documentation on making a user an organization owner from the terminal to mark the appropriate users as organization owners.

3. All users from your previous workspace will have accounts in your new Zulip organization. However, you will need to let users know about their new accounts, and how they will log in for the first time .

4. Share the URL for your new Zulip organization, and (recommended) the Getting started with Zulip guide.

5. Migrate any integrations.

{end_tabs}

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.

!!! warn ""

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.

!!! tip ""

For security reasons, passwords are never exported.

Related articles

• Choosing between Zulip Cloud and self-hosting
• Setting up your organization
• Getting started with Zulip