Skip to main content

Git sync

Hex projects can be synced with either a GitHub or a GitLab repository. Hex projects are represented in git repos as YAML files that describe the logic and configurations of each cell in a Hex project, as well as information about your app layout. You can read more about the file format here.

This feature lets teams:

  1. Have a copy of their code outside of Hex, which becomes searchable and auditable.
  2. Make bulk changes to projects (for example, updating SQL), that can be re-imported into Hex.
  3. Optionally, implement a Pull Request workflow when publishing projects.

Hex projects can be synced to a git repo on a per-project basis. Today, Hex writes to a default branch – however, we plan to introduce more advanced workflows (like reviews and branching) in the future.

Once git sync is enabled for a project, saving a new version or publishing your project will write a commit to a develop branch in your repository. When you publish this version of the app, Hex will merge those commits onto your specified publish branch.

Upstream changes on that branch a remote repository can also be pulled into Hex.

Set up a git sync repo

Only Admins are able to set up git sync repositories. To do so:

  • Head to the Workspace assets panel of the Settings page
  • Click "Connect" for either GitHub or GitLab, and go through the OAuth flow
  • Add a sync repository using the "+ Repository" button
  • Choose a publish branch: this is the branch that will reflect the published version of your app
  • Additionally choose whether Pull Requests are required for publishing an app
  • Choose which groups are able to write to the repository

We recommend that you start off with a single repo for git sync: it is possible to sync different projects to different repos, but only reach for that if you have a specific problem to solve.

Sync a Hex project to a git repo

To sync a project with a GitHub or GitLab repo:

  1. From the History & versions tab of the left side panel, turn on git sync. If multiple repos are enabled for your workspace, you’ll be able to choose which repo to sync to.
  2. Choose a file path that you would like Hex to use as the name of the synced file — by default, Hex will choose a file path that matches your project name.

Each time you save a version of your work, a commit will be written to a working branch (a separate branch per project). The commit will use the current Hex user’s email as the author.

If pull requests are not required on this repo, then when you next publish your project:

  • If a version hasn’t been saved before publishing, you’ll first be prompted to save a version to represent it as a commit in GitHub/GitLab
  • On publishing, Hex will merge the commits to your publish branch.

If pull requests are required on this repo, then when you next publish your project:

  • If a version hasn’t been saved before publishing, you’ll first be prompted to save a version to represent it as a commit in GitHub/GitLab
  • Hex will then check whether the version on your working branch matches the version on your published branch. If it does not, you’ll be prevented from publishing, and prompted to open a pull request. Once these versions match, you’ll be able to proceed through the flow.
  • Then, you’ll be able to publish the changes to your project.

Pulling upstream changes into Hex

If changes have been made in the git repo outside of Hex (e.g. updating SQL based on a global find and replace, or commits made in the git repo's UI based on suggestions), you can pull the latest version of the file that exists in your git repo into your Hex project via the Pull from working branch button.


If the latest commit on the file in your git repo matches the commit associated with the most-recently saved version of your Hex project, Hex will let you know that there’s nothing to import. If there has been a more recent commit, you’ll get to preview those changes before importing them.

We've built git sync with the assumption that most changes to your Hex projects will be made in Hex directly (rather than in a code editor), and this assumption has been reflected in product decisions. As such, we recommend that you use Hex to write your code as much as possible.

Resolving sync issues

At times, you may get into a state where Hex is unable to represent your latest version of your project as a commit. This can happen for one of two reasons:

Scenario 1: Changes have been made in both Hex and upstream in the repository.

As an example:

  1. A data team member makes changes to update the SQL in all synced projects to use a new schema. These changes are made by cloning the repository, and performing a global find and replace. The changes are represented as a new commit in the repository, but are not pulled into Hex.
  2. Meanwhile, you have made changes to the draft version of your project.

When you go to save a new version, or publish your app, Hex checks that the latest commit on your file in your git repo matches the commit associated with the previous known version. In this case, they won’t match up, since your git repo is ahead of your local version.

Hex will save your version, but the git sync will be paused until this state is resolved.

Your next steps will depend on which version you believe is most up to date:

  1. I only want to keep the changes I’ve made in Hex: To re-enable git sync, force push your latest changes to your repo.
  2. I only want to keep the changes from my git repository: To re-enable git sync, pull the latest version from git as a new version.
  3. I want to keep changes from both the upstream version, and from my version in Hex. Presently, Hex does not support resolving merge conflicts. To keep both sets of these changes, export a copy of your project to a local file, and resolve the sets of changes manually.

Scenario 2: Hex is unable to communicate with your git repository

This could be for a number of reasons, for example:

  • The credentials used to connect to your git repository are no longer valid
  • GitHub/GitLab may be experiencing an outage

If this happens, contact a Hex Admin to check that the git repo is successfully connected.


Can I require git sync for all my projects?

Currently, git sync is enabled at the project level. If you have feedback on how you’d like this configured, please let us know.

What happens if I turn off git sync?

If git sync is turned off for a project, Hex will write a commit to your git repository to delete the file.

How do I change the name of the file that I’m writing to?

If you would like to change the name of the file you are writing to, make sure to do this from Hex.

  1. First ensure there are no other changes on your draft version
  2. Update the file path you want to write to from Hex
  3. Immediately publish a new version

When publishing this new version, Hex will create a pull request for you that includes a commit that changes the name of the file. Note that if this pull request includes other changes, you may end up in a broken state.

Additionally, if you rename the file from your git repository first, Hex will not be able to resolve this change.

How do I incorporate suggestions from a pull request review?

If a reviewer made suggestions on your pull request that were then committed in the GitHub/GitLab UI, you'll need to import these changes back into Hex to continue publishing your project. This is because the version of your project in your git repository is now ahead of the version in Hex.

To import these changes, go to the History & versions sidebar, and pull the changes from your working branch.