Skip to main content

GitHub sync

Hex projects can be synced with a GitHub repository. Hex projects are represented in GitHub 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 GitHub 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 GitHub 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 GitHub sync repo#

Only Administrators are able to set up a GitHub sync repo. To do so:

  • Head to the Settings & administration panel
  • Connect to the GitHub repo
  • 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 teams are able to write this repo.

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

Admins can set up repos for GitHub sync.

Sync a Hex project to GitHub#

To sync a project to GitHub:

  1. From the History & versions tab of the left side panel turn on GitHub 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
  • 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
  • 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 in GitHub. 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 GitHub repo outside of Hex (e.g. updating SQL based on a global find and replace, or commits made in the GitHub UI based on suggestions), you can pull the latest version of the file on GitHub into your Hex project via the Pull from working branch button.

Pull upstream change into your draft Hex project.

If the latest commit on the file in GitHub 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 the GitHub 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 GitHub matches the commit associated with the previous known version. In this case, they won’t match up, since your GitHub repo is ahead of your local version.

Hex will save your version, but the GitHub 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 GitHub: 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 GitHub repository

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

  • The credentials used to connect to GitHub are no longer valid
  • GitHub may be experiencing an outage

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


Can I require GitHub sync for all my projects?

Currently, GitHub 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 GitHub sync?

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

What happens if I change the name of the file that I’m writing to? Hex will write a commit to rename the file.

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 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 GitHub 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.