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.
14 Comments
This is an exciting new feature. Our company uses CodeCommit from AWS to manage its git repositories, so we’ll have to wait and see if support rolls out for other git-based connections.
In the meantime, you may wish to run a quick find-replace through the text of this article for “GithHub” and “GutHub” :)
Thanks for sharing Jameson. Looks like we have a couple spelling errors we need to take care of on our end!
I'll pass this along to our documentation team to get corrected :)
Cheers!
Hi Jameson,
How embarrassing! Thanks for the heads up. Not sure what was going on there with all those GithHubs." We had corrected it and somehow it came back.
Anyway, thanks for letting us know. It's all fixed now!
Thanks!
Thanks for releasing that feature, guys.
Was missing it really much.
Seems that `script.js` also should within a root of the repo?
We have all tooling in the root, including manifest.json, but the final theme itself is located under `_dist` folder.
How to deal with that in our case?
Hey Alexey,
It looks like you haven't received a response on this post so apologies for that :( . Were you able to get things sorted on your end or are you running into any issues?
Let me know!
Hey Alexey,
Most tools allow you to configure where to place the distribution file. You should be able to have it being produced to script.js.
Please create a support ticket if you are unable to do so and we can try to help.
Augusto
Does that mean, my theme will be automatically built and published when I push to Github?
I'm trying to add a GitHub repo from my organization. I enter the username and repo name in the box and click "Import" but then I get an error: "Failed to import theme"
I've checked and double checked my settings and can't find anything wrong. I suspect the problem is due to this being a repo attached to an organization which I'm a part of vs. a repo being in my personal account. I have full access to the repo, however, so there isn't any reason why it shouldn't work.
Hey Matthew Bass,
Because the repo belongs to an organization, an organization admin needs to approve the application before it can access the repository.
You can read more about it in https://support.zendesk.com/hc/en-us/articles/360019773614-Troubleshooting-the-Github-integration-for-Guide-themes and in https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/approving-oauth-apps-for-your-organization
Hope this helps
Hi Augusto,
I am now an organization admin, but I'm still getting the same error when I try adding the repo.
I revoked access to Zendesk from my personal account's "Authorized OAuth Apps" before trying again. I no longer get an OAuth dialog prompting me to grant permission when I try adding the repo. This is strange since I definitely revoked access and would expect to see the dialog again.
I don't see Zendesk listed in the OAuth Apps under our organization either, and I can't seem to get it added there since I'm no longer being prompted with OAuth authorization when I try adding the repo. Any ideas?
Hi Matt,
That's strange. Please try again now and see if the situation improved. The oauth flow only appears after inputting the repo name, so you will need to attempt to import the repo again before seeing the oauth screen.
If you are still experiencing issues, please send us a support request.
Hi Augusto,
I tried again just now and did get the OAuth screen, but after granting access I once again got the "Failed to import theme" error message. I'll open a support request.
Are there any plans to support specifying a `dist` folder for the theme? Using any sort of build pipeline is pretty much a necessity these days so requiring that the top level folder contain the theme itself is a huge pain.
Also, are there any plans to support automatic deployments? For example listening to github webhooks when a commit is merged to master and passes CI?
Both these features would really improve the developer experience.
Hey Cameron Mochrie,
For advanced use cases, we suggest using the Themes API - it allows you to upload theme ZIP packages, so it is very versatile and you can setup a CI workflow using it.
You can see an example of it in action in the Copenhagen Theme repo using Github Actions: we import a theme to test it with Lighthouse.
Please sign in to leave a comment.