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 organization must be on a paid Mode Business plan.
  • You must be an admin of your Mode organization.
  • You must be authorized to install the Mode GitHub app in your GitHub organization.

How it works

Mode → GitHub

Edit reports in Mode as usual. When you are ready to push changes for report to GitHub, click Report 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 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 Organization Settings.
  3. 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 master in your GitHub repository will automatically trigger a push to Mode.

Uncommitted changes in Mode

If you push changes for a given object (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:

In Mode In GitHub
A A
B* B
C C*
  • 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 master branch. Therefore, C (the changes to Report C) will not be visible in Mode.

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

Pull requests

Changes to a branch other than master 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 master.

Merging changes to master

Merge to the master 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.

Merge GitHub changes

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 organization to your GitHub repository, the following assets will be synced:

  • Reports in all open and private Spaces (reports in users’ personal Spaces or the community Space will not be synced)
  • Custom themes
  • Definitions

The repository will be structured as follows:

Mode/                // Each Mode organization  into "Mode" directory in the repo
├── org-foo/         // Directory name is org username
|  ├── definitions/
|  |  ├── definition-1.sql
|  |  └── definition-2.sql
|  ├── spaces/
|  |  └── space_foo/
|  |      ├── report_foo.token/
|  |      |   ├── 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 organization 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

  3. Install the Mode GitHub app

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

    GitHub Mode app

  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 organization

    1. On the top left of Mode home page, click on your account and select Organization 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 organization’s existing Mode-GitHub sync:

  1. On the top left of Mode home page, click on your name and select Organization 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.

Last updated May 17, 2018