Setting Up and Using the Git Sync Plugin

With GitHub's recent change of repository default branches being named 'main' instead of 'master' the following work-around is needed until GitHub also addresses automatic default branch re-routing:

  1. Once you have created your new repo, create a new branch called 'Master'
  2. Set the default branch of the repo to this newly created 'Master' branch

Video Transcript

Hello everyone! In this video, we’re going to set up the GitSync plugin on our Grav website.

GitSync is an easy solution to automatically synchronize your Grav website with a Git repository on services like GitHub, GitLab, and BitBucket.

Setting it up is easy! All you need is a Git Repo and a Grav site. Here’s how:

First, install the Git Sync Plugin - once the plugin is installed a four-step Wizard will automatically appear.

Step 1

  • Select the Next button to start Step 1.
  • Select your Git service of choice. In our example, we’ll use GitHub.
  • Enter your username and either your password or a security token generated by the service you choose.
  • Select Next to start the second step.

Step 2

  • In this step, you will need to have a Git Repository ready. Let’s go ahead and set one up on GitHub.
  • Log in to GitHub and head to your dashboard.
  • Select the plus sign in the upper-right corner and choose New Repository.
  • Give your repository a name and set its security settings. GitSync works whether the repo is public or private, as long as you have access to the repository through your credentials.
  • Now, select the Initialize this repository with a readme box and select * Create Repository. [Some Grav skeletons include a ReadMe file in the User folder. If this is the case, you should delete it prior to completing the installation of Git Sync. This will prevent any issues caused by having two files with identical names being synced at the same time.]
  • You now have a brand new repository we can use to sync with your grav site.
  • Now you just need to find the git link for the repository. On github, you can do this by selecting the green Clone or Download button and copying the Clone with HTTPS link.
  • With this link in your system’s clipboard, flip back to the wizard and enter that URL in the Git Repository field and hit Test Connection.
  • Once you have a successful test, click Next.

Step 3

  • Now we’re going to create a webhook that Git Sync will use to connect with GitHub. This hook allows your site to detect new content on your repository and pull it down.
  • To do this: First copy the Payload URL from the text area labeled “Payload URL:”
  • Next, head to the repository on GitHub and click on Settings
  • Click on Webhooks in the left sidebar
  • Click on the Add webhook-button on the right.
  • Paste the URL you have previously copied into the Payload URL field on GitHub
  • Leaving everything else at its default state, Click the Add webhook-button Now just head back to the Git Sync wizard tab and select next.

Step 4

  • In this final step, we’re going to choose which data we want to synchronize.
  • You can synchronize the site’s content using the pages option, but you also have the ability to sync its ‘themes’, ‘plugins’, ‘config’ and ‘data’ folders. When syncing Pages any changes you make in the Admin Panel are automatically synced by the Git Sync Plugin. Syncing the Themes folder is an excellent way to collaborate with other Grav site authors to help you with theme modifications. However, be mindful of syncing the Config and Data folders as they may contain information related to the security of your website and should only be synced if you are absolutely sure your repository is secure and private.
  • Once you’ve selected what you want to sync, hit save.
  • After doing this, you’re done. You should be able to see your sites data appear in your github repo. To test the connection further, you can make a small change on one of the files in the repository and check to see if that change appears on your website.

Notice an error? Think you can improve this documentation? Edit this Page