Overview

You can connect Mode to a GitHub repository of your choice. This will create a two-way sync between Mode and GitHub, where changes made in Mode can be pushed to the GitHub repository, and changes made in GitHub will be automatically pushed to Mode.

Requirements

Before you begin, you must meet the following requirements in order to set up the Mode sync with GitHub:

• Your Mode Workspace must be on one of Mode's paid plans.
• You must be an admin of your Mode Workspace.
• You must be authorized to install the Mode GitHub app in your GitHub organization.
• In GitHub, create a new repository or select an existing repository for Mode.
• The default branch cannot be protected and must be titled either “main” or “master”.

How it works

Mode → GitHub

Edit Datasets, Reports, or Definitions in Mode as usual and move Datasets and Reports to a Workspace collection. Datasets and Reports in users' personal Collections or the community Collection will not be synced.

When you are ready to push changes for a Dataset to Github, edit the Dataset, and click on ▼ next to the Dataset name and then Push to GitHub.

To push changes for a Report to GitHub, edit the Report, click Report in the menu and then Push to GitHub.

To push changes for a Definition to GitHub, edit the Definition, click More in the menu and then Push to GitHub.

Enter a commit message to describe the changes, and your updates will be pushed to GitHub.

Batch updates from Mode → GitHub

Mode admins can push the latest version of all Datasets, Reports, Definitions, and themes from Mode to GitHub in a batch update.

To push all updates:

1. Navigate to the Mode home page and click on your name in the upper left corner of the window.
2. Click Workspace Settings.
3. Under the Features section, click GitHub.
4. Under the Unresolved Differences tab, click Push All.

This will resolve any differences between Mode and GitHub by overwriting what's in GitHub with what's in Mode. Please note that this may take a few minutes.

GitHub → Mode

Any commit to the default branch in your GitHub repository will automatically trigger a push to Mode.

Uncommitted changes in Mode

If you push changes for a given object (Dataset, Report, Definition, or theme) from GitHub to Mode, your push will only affect that object. In other words, you will not overwrite uncommitted changes to other objects in Mode.

For example, say you have three reports in Mode:

• Report A is the same in both Mode and GitHub.
• Report B has been updated in Mode (B*) but has not been synced to Github.
• Report C has been updated in a branch on Github (C*) but that branch has not yet been merged with the default branch. Therefore, C* (the changes to report C) will not be visible in Mode.

When the branch containing C* is merged with the default branch, Report C in Mode will updated to C*. However, B* will not be overwritten by B.

Pull requests

Changes to a branch other than the default branch won't be reflected in Mode. You can create branches and open pull requests in GitHub as normal without affecting your reports in Mode until those branches are merged into the default branch.

Merging changes to default branch

Merge to the default branch in GitHub and changes will automatically sync to Mode. If your branch causes any issues, you can revert back to the previous version in GitHub.

Note that the owner of your GitHub organization will need to install the Mode GitHub app in order to use the Mode Github sync.

Repository structure

When you connect your Mode Workspace to your GitHub repository, the following assets will be synced:

• Datasets and Reports in all open and private Collections (Datasets and Reports in users' personal Collections or the community Collection will not be synced)
• Custom themes
• Definitions

The repository will be structured as follows:

Mode/                // Each Mode Workspace  into "Mode" directory in the repo
├── org-foo/         // Directory name is org username
|  ├── definitions/
|  |  ├── definition-1.sql
|  |  └── definition-2.sql
|  ├── spaces/
|  |  └── space_foo/
|  |      ├── dataset-1.dataset.token/
|  |      |   ├── query-1.token.sql
|  |      ├── report_foo.token/
|  |      |   ├── dataset-1.dataset.token.sql
|  |      |   ├── query-1.token.sql
|  |      |   ├── query-2.token.sql
|  |      |   ├── index.html
|  |      |   ├── settings.yml
|  |      |   └── python-notebook/
|  |      |       ├── cell-1.token.py
|  |      |       └── cell-2.token.py
|  |      ├── report_bar.token/
|  |      |   ├── query-1.token.sql
|  |      |   ├── query-2.token.sql
|  |      |   ├── index.html
|  |      |   ├── settings.yml
|  |      |   └── python-notebook/
|  |      |       ├── cell-1.token.py
|  |      |       └── cell-2.token.py
|  |      └── archived/
|  |          └──report_old.token/
|  |             ├── query-1.token.sql
|  |             ├── query-2.token.sql
|  |             ├── index.html
|  |             └── settings.yml
|  ├── themes/
|  |  ├── theme-1.css
|  |  └── theme-2.css
|  └── README.md

All code pushed from your Mode Workspace to your GitHub repository will be stored under a top-level directory called Mode. This is to allow you to nest other analytics code (e.g. dbt, airflow, etc.) within this repository.

Setting up the sync

1. Create a GitHub organization if you don't already have one

   Mode's GitHub sync requires your repo to be part of a GitHub organization. Learn more about creating a GitHub organization.

2. Create a new repository in GitHub for your Mode assets

   Note: While we suggest this repository be solely dedicated to syncing with Mode, other top-level folders in the repository will not be affected.

3. Install the Mode GitHub app

   Navigate to the installation page for Mode's GitHub app and click Configure. Confirm the installation location and then select the repository you'd like to use.

   

4. Retrieve the installation ID for your Mode GitHub app

   The ID appears as numerical code at the end of the installation success page's URL, for example 88888 in this URL:

   https://github.com/settings/installations/88888

5. Configure your Mode Workspace

   1. On the top left of Mode home page, click on your account and select Workspace Settings.
   2. Select GitHub from the left navigation panel under Features.
   3. Input your GitHub organization name, GitHub repository name, and installation ID.
   4. Click Initialize Setup. This may take a few minutes to complete.

Maintaining your repository

Modifying the sync

Mode does not support editing the repository name or the GitHub organization name. Changes to these names on GitHub will cause the Mode-GitHub sync to break. If you'd like to change the repository you use for the sync, you will have to delete your existing sync in Mode and restart the setup process.

Deleting the sync

Deleting your GitHub sync details from Mode will prevent Mode from syncing changes with your GitHub repo, but it will not remove your repo. To delete your Workspace's existing Mode-GitHub sync:

1. On the top left of Mode home page, click on your name and select Workspace Settings.
2. Select GitHub from the left navigation panel under Features.
3. Click on the gear icon next to GitHub and select Delete.

User administration

Administration of users will be up to you. Anyone making changes through the Mode UI can push those changes to GitHub. However, if users want to make changes in GitHub they'll need to be added to the GitHub repository.

Repository visibility

If you have non-Mode data in the GitHub repository used for the Mode-GitHub sync, please be aware that Mode has visibility to the entire repository.

FAQs

Q: Where is the button for admins to push all reports to Github all at once

The "Push All" button is found by accessing the Workspace Settings menu, going to the GitHub tab under Features (highlighted in red below), selecting the Unresolved Differences tab (highlighted in orange below), and looking on the right side of the Resolve All Differences section (highlighted in pink below). 

Q: Are restricted collections synced to GitHub?

Both restricted and public collections are synced to Github. Reports in users' personal Collections or the community Collection will not be synced.