Skip to main content

Connect to GitHub, GitLab, Bitbucket, and more

Note

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

Introduction​

Holistics stores your analytics code in an internal Git repository by default. Connecting it to your own external repository lets you use your team's existing Git tools and workflows on GitHub, GitLab, Bitbucket, or any SSH-compatible provider.

Benefits of connecting an external repository:

  • Enforce code review before changes go live. Require pull request approvals so no change reaches production without a review.
  • Integrate with your CI/CD pipeline. Auto-publish to Holistics production whenever a PR is merged to master.
  • Work in your local editor. Use VS Code or any editor to write and manage your analytics code, then push changes directly.
  • Keep your code in your own account. Your team gets a full copy of the analytics codebase, visible in your company's Git history.

How it works​

When you connect an external repository, Holistics mirrors your analytics code there.

  • Any change made in Holistics, on any branch, is pushed to the corresponding branch in your external repo.
  • The master branch is treated as production: pushing or merging changes into master externally will trigger an auto-publish to Holistics production, but only if you've set up the Pull Request workflow or Publish API.

How to connect​

info

Your external repository must be completely empty: no commits, no README, no LICENSE, no default files of any kind.

  1. Create an empty Git repository on your provider of choice.

    Regardless of which provider you use, make sure not to initialize the repository with any default files (README, LICENSE, etc.). Below is an example for GitHub:

  2. In Holistics, navigate to the Version Control Settings page.

    Holistics Version Control Settings page with 'Connect to Git Provider' button.

  3. In the Connect Git Provider dialog, select your provider, GitHub, GitLab, or Other (for Bitbucket and any other SSH-compatible provider). Then enter your repository's SSH URL and click Continue.

  4. Holistics will generate a Deploy Key for your repository. Copy it and add it to your repository's settings:

    Holistics 'Connect Git Provider' dialog showing the generated Deploy Key to be copied.

    Make sure to enable Allow write access — Holistics needs this to sync changes back to your repo.

    Git provider settings page for adding a deploy key, with the 'Allow write access' option highlighted.
    info

    The Deploy Key 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 established, Holistics initializes your repository with a master branch and a set of folders — one for each object type that's synced.

After connecting​

Here's how the sync works once you're connected:

  • Holistics → external repo: Any commit made in Holistics is automatically pushed to the corresponding branch in your external repository.
  • External repo → Holistics production: Changes merged into master in your external repo will be auto-published to Holistics production, as long as:

To get the most out of this setup, consider enforcing a pull request & code review process on your external repository.

danger

Do not rewrite or modify commit history (e.g. force push) in your external repository. Holistics' sync depends on linear commit history, modifying it can cause unexpected behavior.

Frequently Asked Questions​

Dialog box confirming unlinking from an external Git repository

No worries, unlinking won't delete your changes or break anything. Your projects and dashboards keep 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 the repository is either:

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

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

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

Here's how to switch providers:

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

4. Does Holistics support Bitbucket or other Git providers?​

Yes, Bitbucket and any Git provider that supports SSH connections will work. In the Connect Git Provider dialog, select Other and enter your repository's SSH URL.

For custom Git domains (e.g. a self-hosted GitLab or Gitea instance), 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?​

Short answer: Holistics only stores the private key on our servers, your Git provider only ever receives the public key, which is harmless on its own.

In more detail, when you connect, Holistics generates an SSH key pair:

  • Public Key: This is what you paste into your Git provider's settings. Even if exposed, it grants no repository access without the corresponding private key.
  • Private Key: Stays on Holistics servers and is never exposed. It's protected with multiple layers:
    • Encrypted with a passphrase
    • The passphrase itself is also encrypted
    • Stored in secure infrastructure with strict access controls

Additional security properties:

  • The Deploy Key is scoped to a single repository, no broader account access
  • You control write permissions via the "Allow write access" toggle in your Git provider
  • You can revoke access instantly by removing the key from your repository settings
  • No OAuth tokens or app credentials are stored
Let us know what you think about this document :)