Themes

This guide covers how to create, edit, and manage Zendesk themes at GitLab. Administrators should review the Administrator tasks section.

Understanding themes

What are themes

A theme is a set of files that determine what your support portal looks like.

How we manage themes

While Zendesk offers a full way to manage themes via the UI, we turn to a more version controlled methodology. This allows for a set review process, the ability to perform rollbacks as needed, etc.

That being the case, we utilize sync repos.

Creating a theme as a non-admin

For the creation of a theme, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Editing a theme as a non-admin

For the modification of a theme, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Changing the live theme as a non-admin

To change the live theme, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Deleting a theme as a non-admin

To request the deletion of a theme, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Administrator tasks

Viewing themes in Zendesk

To view the themes in Zendesk:

1. Access the knowledge center
2. Click the Customize design icon on the left side:
   • For the primary brand:
     • Zendesk Global (production)
     • Zendesk Global (sandbox)
     • Zendesk US Government (production)
     • Zendesk US Government (sandbox)
   • For the internal brand:
     • Zendesk Global (production)
     • Zendesk Global (sandbox)
     • Zendesk US Government (production)
     • Zendesk US Government (sandbox)

Creating a theme

This is a very complex process to integrate into our systems. As such, please have a Fullstack Engineer for the Customer Support Operations team assist you in this. It is a very manual process.

Editing a theme

To edit a theme, you will need to create a MR in the sync repo. The exact changes being made will depend on the request itself, but make sure to use our Versioning information in your changes.

Once the MR is created, a preview link will be generated in the MR comments. This link allows you to preview theme changes before merging. If you push new commits to your MR, a new preview link will be generated.

After a peer reviews and approves your MR, you can merge the MR.

Once merged, any preview themes generated (for preview links) will be deleted via automation from the system. Once that completes, it will fully merge into the default branch.

When the next deployment occurs, it will be synced to Zendesk.

Versioning information

It is vital for the theme that we use the correct versioning style. The version itself stems from the data/theme/manifest.json file’s version attribute. It uses 3 digits separated by a period. When making changes, keep the meaning of these digits in mind:

• The first digit: should always match the api_version attribute
• The second digit: when creating a new MR, you should take the previous value and add 1 to it
• The third digit:
  • when creating a new MR, it should be 0 (see Example 1)
  • If you push new changes to the MR after creation, you should add 1 to it (see Example 2)

Example 1

You need to perform changes to the theme, so you develop them and then create a new MR. The data/theme/manifest.json file had the following in it before you made any changes:

{
  "name": "GitLab Zendesk Global Theme",
  "author": "Jason Colyer",
  "version": "4.0.39",
  "api_version": 4,
  "default_locale": "en-us",

Since you are creating a new MR, the new value should look like this:

{
  "name": "GitLab Zendesk Global Theme",
  "author": "Jason Colyer",
  "version": "4.1.0",
  "api_version": 4,
  "default_locale": "en-us",

If, after creation, you needed to push new changes to the MR, the new value should look like this:

{
  "name": "GitLab Zendesk Global Theme",
  "author": "Jason Colyer",
  "version": "4.1.1",
  "api_version": 4,
  "default_locale": "en-us",

Example 2

You are working with a peer on an existing MR for theme changes. After your development, you decide to push changes to the existing MR. The data/theme/manifest.json file had the following in it before you made any changes:

{
  "name": "GitLab Zendesk US Government Theme",
  "author": "Jason Colyer",
  "version": "4.10.9",
  "api_version": 4,
  "default_locale": "en-us",

Since the MR already existed and you are pushing new changes, the new value should look like this:

{
  "name": "GitLab Zendesk US Government Theme",
  "author": "Jason Colyer",
  "version": "4.10.10",
  "api_version": 4,
  "default_locale": "en-us",

Changing the live theme

This is a very complex process to integrate into our systems. As such, please have a Fullstack Engineer for the Customer Support Operations team assist you in this. It is a very manual process.

Deleting a theme

If deleting a non-live theme, you may proceed as normal. To do this:

1. Navigate the themes listing
2. Locate the theme in question and click the three vertical dots to the right side of it
3. Click Delete
4. Click Delete theme to confirm the deletion

Performing an exception deployment

To perform an exception deployment for themes, navigate to the themes sync project in question, go to the scheduled pipelines page, and click the play button for the sync item. This will trigger a sync job for the themes.

Common issues and troubleshooting

Not seeing theme changes after a merge

As themes follow the Standard deployment type, they would only be deployed during a normal deployment cycle (or when an exception deployment has been done)

View page source - Edit this page - please contribute.