Zendesk Sync Repo Training

Maintained by:

What this covers

This training material will cover the following topics:

A broad overview of what Zendesk sync repos are
Why we use Zendesk sync repos
How Zendesk sync repos work
Creating a new item in a sync repo
Updating existing items in a sync repo
Deactivating items in a sync repo

What are Zendesk sync repos

Zendesk sync repos refer to various projects (see useful links) GitLab utilizes to manage the various components of Zendesk. Utilizing scripting and CI/CD, changes to these projects are synced to Zendesk.

Why we use Zendesk sync repos

Using sync repos with Zendesk enhances the capabilities of Zendesk primarily by:

making it easier to manage changes.
making rolling back changes quick and easy.
ensuring a review process is in place.
creating a version-controlled environment.

Zendesk natively supports versioning for triggers, however, we found we desired a version-controlled environment for as many aspects of Zendesk as was possible. To this end, we created the sync repos.

How the Zendesk sync repos work

While there is some variance between the repos, in general, the process goes as follows:

A JSON file is generated containing all the information from the sync repo.
A JSON file is generated containing all the information from Zendesk.
The two JSON files are compared. Results form two files, an updates file and a creates file.
The creates file is parsed and new items are created in Zendesk.
The updates file is parsed and existing items are updated in Zendesk.

For a more in-depth look at how they work on the code level, please check out the below video:

Creating a new item

While the scripts can handle creation (to a degree), we prefer to update an existing item instead. That section and its video will cover creating a new item.

Updating an existing item

When the item already exists in the sync repo, you simply edit the file and create a merge request. Once reviewed, approved, and merged, this will sync the changes over to Zendesk.

When the item does not exist, we still use the "updates" approach of the script. To do this, first copy an existing item in Zendesk and then deactivate it. This new item will have a Zendesk ID. From there, you can generate the file in the sync repo using that item's Zendesk ID. The scripts will see this as an "update", but in reality, you are creating a new item.

In the case where you are trying to do this without an ID, you can still create the file and leave the id: line blank. Doing so might make the scripts fail during testing, but someone with admin access to Zendesk will assist from there.

Deactivating items in a sync repo

To deactivate an item in the sync repo (as we avoid deletion when at all possible), you need to follow specific steps:

Move the file to the inactive folder.
Edit the file to change active: true to active: false.

Doing it outside of that order can result in it not actually committing the file change. By doing it in that specific order, you ensure the item is fully deactivated in the sync repo and will therefore sync properly to Zendesk.

Useful links

Zendesk Global sync repos
Zendesk US Federal sync repos