Setting up the GitHub integration

Jess Bezos
Jess Bezos

The GitHub integration enables you to develop and maintain a theme collaboratively in GitHub, then preview or publish it in Guide. To set up the integration, make sure your theme is stored in GitHub, then set up the integration in Guide.

You must be a Guide Manager to set up the GitHub integration in Guide.

Preparing your theme in GitHub

You need to ensure that your theme is in GitHub before you set up the integration in Guide. If you’re new to Git and GitHub check out this tutorial. If your theme is already in GitHub, and it meets the following requirements, see Setting up the integration in Guide.

The integration has the following requirements for your GitHub repo:

  • The manifest file must be at the root of the GitHub repo

    The file manifest.json should be placed at the root of your GitHub repository for Guide to be able to fetch your theme. You can still include extra files, such as tooling, which are ignored when importing to Guide.

  • The GitHub repo can have only one theme

    You should only manage one theme in each repository. You can use the branch option during theme import to try out variations of your theme.

To get your theme into a GitHub repo

  • If your theme is in Guide, export your theme from Guide and create a GitHub repo (if you don’t already have one) and push your theme to the GitHub repo.

  • If your theme is not in Guide or GitHub, create a GitHub repo (if you don’t already have one) and push your theme to the GitHub repo.

After you’ve prepared your theme in GitHub, you are ready to set up the integration in Guide.

Setting up the integration

To set up the GitHub integration you need to make sure your theme is stored in GitHub, then fetch your theme from GitHub to Guide. This one-time fetch establishes the connection between your theme and GitHub.

After you set up the integration, you will work on the theme in GitHub, then update the theme in Guide when you’re ready. In Guide you can then preview or publish the theme live.

To set up the GitHub integration with your Guide theme

  1. In GitHub, ensure that you have prepared your theme.
  2. In Guide, click the Customize design icon (guide_icon_customize) in the sidebar.

    The Themes page opens.

  3. Click Add new theme in the upper-right corner.
  4. Click Fetch from GitHub.

    Add new theme

  5. Enter the URL for the repo and, optionally, enter a branch name if you want to fetch from a branch other than the default branch, then click Import.
  6. Log in to GitHub if prompted, then click Authorize Zendesk.

The theme thumbnail appears on the Themes page when the import is complete. If you have problems, see Troubleshooting the GitHub integration for Guide themes.

Once you’ve established the connection between your theme in Guide and GitHub, you will manage your theme in GitHub and update the theme in Guide as needed.

Was this article helpful?

Comments

3 comments

  • Comment author
    Michelle Perkins

    Hi, I am getting a 'failed to import theme' error. What should I do?

    0
  • Comment author
    Vera Yang

    Hi Michelle, have you tried copy and pasting the repository URL from the address bar when viewing the repository? If you are still getting the error, there are other things to try, see Troubleshooting your Github integration with Guide themes. If you are still having issues then please let us know.

    0
  • Comment author
    Michelle Perkins

    Thanks Vera, that article was helpful. Turns out I had got the branch name wrong! Simple mistake. Thanks again.

    0

Please sign in to leave a comment.