Git sync

Sync your Hex project with a GitHub or GitLab repository.

warning

This page is unlisted because the ability to require pull requests has been deprecated for new connections to repositories. If a repository was previously configured to require pull requests, that behavior will continue to be supported. See our updated docs on Git Export for information on how to configure new connections to repositories.

info

• Available on the Team and Enterprise plans
• Users will need the Admin role to set up git sync repositories.
• Users will need Can Edit permissions or higher to use 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. 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.

Set up a git sync repo

Only Hex Admins are able to set up git sync repositories. The repository access must also be approved by a repository admin on the git side. To do so:

• Head to the Settings → Integrations tab, under the "Workspace" header.
• 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. Note that only a single GitHub account can only be connected to a single Hex Workspace and vice versa.

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.

tip

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 the vast majority of 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.

Git Sync and Reviews

In a given project, it is not possible to use Git Sync with Pull Requests at the same time as Reviews. If you would like to use Hex Reviews while also backing your work up to your Git provider, reach out to [email protected] so we can transition your configuration to use Git Export, which works beautifully with Reviews!

• If a project has Git Sync with Pull Requests enabled: users will not see the option to request a review in the publish modal. They will not be able to enable required reviews on the project.
• If a project does not have Git Sync with Pull Requests enabled: users will be able to request reviews and require reviews. They can also enable Git Sync so long as a review is not in progress.
• If a project requires reviews: users will not be able to enable Git Sync with Pull Requests until they turn off required reviews.
• If a review is in progress: users will not be able to enable Git Sync with Pull Requests until the in-progress review is cllosed or completed.

FAQs

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.

Is Git Sync supported for components?

No, Git Sync can only be enabled for projects.

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.