Skip to main content

Connect to GitHub/GitLab

Note

External Git is available to all customers in Standard Plan and above.

Introduction​

By default, your analytics code in Holistics is kept in an internal Git repository that Holistics maintains. In case you want to have more granular control of your code base, you can easily connect your Holistics account with an external repository in GitHub or GitLab.

Benefits of using an external repository:

  • You have direct access to a backup version of your analytics code.
  • You can apply proper data governance and quality control protocols by enabling review workflow in Holistics.
  • You can leverage your own local editor (i.e. VS Code) to manage Holistics modeling layer and push changes back to Holistics conveniently.

How to connect to your external Git repository​

info

Ensure that your external Git repository is a bare repository. It must not have any commits, or contain any default files like README.md, LICENSE.md, etc.

  1. Create an empty Git repository (without a README) on GitHub, GitLab or any Git-based version control platform of choice.
If you use Github to initialize a new repository

When initializing a new repository in Github, be careful not to select the options to generate default files.

  1. Navigate to the Version Control Settings page.

  2. Get the SSH URL for the external Git repository.

  3. Paste the SSH URL into the “SSH URL” field on the Version Control Settings page.

  4. Copy the Deploy Key which Holistics provides on the Version Control Settings page and paste it into the Settings for the repository:

    Make sure to select the Allow write access option because Holistics requires this setting to make and deploy changes.

    info

    The Deploy Key you're pasting is a public key - even if exposed, it can't be used to access your repository on its own. Learn more about how Deploy Keys are secured.

  5. Navigate back to the Version Control Settings page and click Test connection.

  6. Once the connection is successfully established, a new master branch will appear in the repository, along with a set of folders, one for each object type that is synced. Holistics will then sync with the master branch in the repository as the Production branch.

Notes:

  • Any changes made in Holistics will be synced to the external repository at the corresponding branches.
  • To make full use of your new setup with an external Git repository, you can take an extra step and enforce a pull request & code review process.
  • Any changes merged into the master branch in the external repository will be automatically published to Holistics production if:
    • You have set up auto publish workflow by either:
    • Your changes in external repository don't have any validation errors
Important note

You should not modify the commit history (for e.g., force push) via GitHub or GitLab since it could cause unexpected behavior in Holistics as our "git syncing actions" depend on the commit history.

Frequently Asked Questions​

No worries - unlinking won't delete your changes or break anything. Your projects and dashboards will continue working normally because everything is stored in Holistics' internal repository. You can unlink anytime without any impact.

2. Can I connect Holistics to an existing repository?​

Yes, but only if your repository is either:

  • Completely empty, or
  • Was previously connected to Holistics (i.e., you unlinked it and now want to reconnect)

Otherwise, the Git histories won't match and the connection will fail.

3. How can I migrate my repository (for e.g., from GitHub to GitLab)?​

Here's how to switch providers:

  1. Import your repository to the new platform (e.g., GitHub to GitLab)
  2. In Holistics, unlink your current repository
  3. Connect to the new repository you just imported

4. Does Holistics support custom git domains or other git providers?​

Yes - any Git provider that supports SSH connections will work, including custom Git domains.

For custom domains, we'll need to verify them first for security. Just submit a verification request and our team will review and approve it.

5. How secure is the Deploy Key method?​

Holistics uses Deploy Keys (SSH key pairs) to connect with your Git provider (see step 5 in the connection guide). Our Deploy Key implementation is secure and designed with multiple layers of protection:

How Deploy Keys work in Holistics:​

When you set up the connection, Holistics generates an SSH key pair:

  • Public Key: This is what you paste into your Git provider's Deploy Key settings. Even if this key is exposed, it grants no access to your repository on its own—it can only be used when paired with the corresponding private key.
  • Private Key: This remains securely stored on Holistics servers and is never exposed. The private key is protected with multiple encryption layers:
    • Encrypted with a passphrase
    • The passphrase itself is also encrypted
    • Stored in our secure infrastructure with strict access controls

Security benefits of this approach:​

  • The Deploy Key is scoped to a single repository, limiting potential exposure
  • You control write permissions by toggling the "Allow write access" option in your Git provider
  • You can revoke access instantly by removing the Deploy Key from your repository settings
  • No OAuth tokens or app credentials are stored that could provide broader access to your Git account

This implementation follows SSH key security best practices and provides a secure, reliable connection between Holistics and your Git repository.

Let us know what you think about this document :)