GitHub sync

Overview

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

Requirements

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

  • You must be an admin of your Analyst Studio Workspace.

  • You must be authorized to install the Analyst Studio GitHub app in your GitHub organization.

  • In GitHub, create a new repository or select an existing repository for Analyst Studio.

  • The default branch cannot be protected and must be titled either “main” or “master”.

    A branch must be created prior to starting the integration setup. Analyst Studio will not automatically create a branch as part of this process.

How it works

Analyst Studio → GitHub

Edit Datasets, Reports, or Definitions in Analyst Studio 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 the downward caret ▼ next to the Dataset name, and select Push to GitHub. Merge GitHub changes

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

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

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

Batch updates from Analyst Studio → GitHub

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

To push all updates:

  1. Click the app switcher icon in the top navigation bar and select Analyst Studio, then 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 Analyst Studio and GitHub by overwriting what’s in GitHub with what’s in Analyst Studio. Please note that this may take a few minutes.

GitHub → Analyst Studio

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

Uncommitted changes in Analyst Studio

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

For example, say you have three reports in Analyst Studio:

In Analyst Studio In GitHub

A

A

B*

B

C

C*

  • Report A is the same in both Analyst Studio and GitHub.

  • Report B has been updated in Analyst Studio (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 Analyst Studio.

When the branch containing C* is merged with the default branch, Report C in Analyst Studio will be 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 Analyst Studio. You can create branches and open pull requests in GitHub as normal without affecting your reports in Analyst Studio 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 Analyst Studio. If your branch causes any issues, you can revert to the previous version in GitHub.

Merge GitHub changes

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

Repository structure

When you connect your Analyst Studio 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 Analyst Studio 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 (for example, dbt, airflow, etc.) within this repository.

Setting up the sync

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

    Analyst Studio’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 Analyst Studio assets.

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

  3. Install the Analyst Studio GitHub app.

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

    GitHub Analyst Studio app

  4. Retrieve the installation ID for your Analyst Studio 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 Analyst Studio Workspace.

    1. On the top left of Analyst Studio 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

Analyst Studio does not support editing the repository name or the GitHub organization name. Changes to these names in GitHub will cause the Analyst Studio-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 Analyst Studio and restart the setup process.

Deleting the sync

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

  1. On the top left of Analyst Studio 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 Analyst Studio 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-Analyst Studio data in the GitHub repository used for the Analyst Studio-GitHub sync, please be aware that Analyst Studio 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).

Github Unresolved Differences

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.

Was this page helpful?
×