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 admin 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 add 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 you do not currently have a theme, fork the Copenhagen theme repo and start building your theme. This enables you to easily port improvements from the Copenhagen theme to your theme in the future.
- If your theme is in Guide, download your theme from Guide, then 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
- In GitHub, ensure that you have prepared your theme.
- In Guide, click the Customize design icon () in the sidebar.
The Themes page opens.
- Click Add theme in the upper-right corner.
- Click Add from GitHub.
- 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.
- 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.
After 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.
Is there a possibility to have other Git repo integration e.g. Bitbucket, GitLab - not GitHub?
Artem Fursenko Unfortunately, at this moment we don't have any official integrations with Bitbucket or Gitlab.There might be 3rd party integrations available (via Zapier, for example), but I won't be able to provide detailed information about it. I'd recommend following up our announcement page in case if there are any news regarding this: https://support.zendesk.com/hc/en-us/categories/4405298749210-Zendesk-updates
Hi. Do you have to use Zendesk to preview the output or is there a way of locally checking the changes?
Hi Andrew Mantle
You can work with theme locally using Zendesk app tools (ZAT).
Can you keep help center articles in code in a repo and sync them to Zendesk on a git push?
As it turns out, the option for git push is not supported. I also took the liberty of checking our Marketplace for similar integration but there's none. The only available option when it comes to creating articles if you have your own repository is through Help Center API.
Is it possible to add a private repo to the GH integration? If not, are there any updates on future integrations like BitBucket? I couldn't find any help articles related to those topics. Thank you.
Thanks for reaching out to us! My name is Clifford from the Advocacy department and I'll be the one assisting you with your concern. :)
In regard to your concern with Github Enterprise Cloud, I have reached out internally to our Github team so I will be providing you an update once I confirmed with them.
For the 2nd one, may you please elaborate on managing change conflicts? Can you provide a use case for this?
I look forward to your response!
Hi @... ,
In regards to managing change conflicts, we plan to copy the Zendesk Copenhagen theme repo rather than fork it, that way we can create our own forks privately. From there, we can pull updates from the main repo and marge them with our private fork. Github helps manage change conflict but we wanted to know how Zendesk might help prevent conflicts when updating the theme files?
Is there a possibility to sync with GitLab instead of GitHub? I know it snot possible currently but is the integration with gitlab in the roadmap?
Adeem Basraa A Gitlab integration is not on the roadmap currently, but you could set up your own integration using the Themes API.
Please sign in to leave a comment.