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 triggers an auto-publish to Holistics production, but only if you've set up the Pull Request workflow or Publish API.

How to connect

Holistics supports two connection methods. Pick the one that fits your setup:

[Upcoming] GitHub App (recommended for GitHub users)

Connect at the organization level. One setup enables both code sync and PR workflow, with no SSH keys or personal access tokens to manage. The integration belongs to the organization, so team changes don't break anything.

→ Connect with GitHub App

SSH Deploy Key

Connect using an SSH key pair scoped to a single repository. Required for GitLab, Bitbucket, and other SSH-compatible providers, and available as a fallback for GitHub users who can't install apps on their organization.

→ Connect with SSH Deploy Key

Repository must be empty

Whichever method you choose, your external repository must be either completely empty (no commits, no README, no LICENSE) or previously connected to Holistics. Otherwise the git histories won't match and the connection will fail.

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 are auto-published to Holistics production, as long as:
  • You've set up auto-publish via Pull request workflow (recommended) or the Publish API
  • Your changes have no validation errors

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, and modifying it can cause unexpected behavior.

Frequently Asked Questions

Which connection method should I use?

• GitHub App if you're on GitHub and can install apps on your organization (or you're connecting a personal repo). It's the simplest, most secure setup.
• SSH Deploy Key for GitLab, Bitbucket, self-hosted Git, or when GitHub App install is blocked by your org.

What happens if I unlink my connection to an external 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.

Note that unlinking in Holistics does not uninstall the GitHub App (if you used that method) or remove the Deploy Key from your provider. If you want to fully remove access, do that from your Git provider's settings separately.

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.

Can I switch between connection methods later?

Yes. You can switch between GitHub App and SSH Deploy Key (or vice versa) without recreating your repo. Unlink the current connection, then connect again using the other method. Your branches and commit history are preserved.

See Switching from SSH Deploy Key to GitHub App for details.

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

Does Holistics support Bitbucket or other Git providers?

Yes, Bitbucket and any Git provider that supports SSH connections work via the SSH Deploy Key method. 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.