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.
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 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:
- Navigate to the Mode home page and click on your name in the upper left corner of the window.
- Click Workspace Settings.
- Under the Features section, click GitHub.
- 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 (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|
Ais the same in both Mode and GitHub.
Bhas been updated in Mode (
B*) but has not been synced to Github.
Chas 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
B* will not be overwritten by
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.
When you connect your Mode Workspace to your GitHub repository, the following assets will be synced:
- Reports in all open and private Collections (reports in users' personal Collections or the community Collection will not be synced)
- Custom themes
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/ | | ├── 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 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
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.
Create a new repository in GitHub for your Mode assets
Note: this repository should be solely dedicated to syncing with Mode. Non-Mode files in the Github repo will be deleted by any batch updates.
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.
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:
Configure your Mode Workspace
- On the top left of Mode home page, click on your account and select Workspace Settings.
- Select GitHub from the left navigation panel under Features.
- Input your GitHub organization name, GitHub repository name, and installation ID.
- 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:
- On the top left of Mode home page, click on your name and select Workspace Settings.
- Select GitHub from the left navigation panel under Features.
- Click on the gear icon next to GitHub and select Delete.
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.
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.
Was this article helpful?