Content last updated 2025-12-23

Apps

Documentation on Zendesk apps

This guide covers information and management of Zendesk apps at GitLab.

For a list of currently used apps:

Developers should review the Development documentation.

Administrators should review the Administrator tasks section.

Understanding Zendesk apps

What is a Zendesk App

A Zendesk App is an application (written in HTML/CSS/JS) that runs in a location of Zendesk. What it does and how it does it varies greatly from application to application. Applications can be run in a great many places, but the traditional locations are:

  • Ticket sidebar
  • User sidebar
  • Organization sidebar
  • Navbar
  • Background

You can see more resources on application locations via the Zendesk Developer Manifest Reference documentation.

Zendesk applications tend to come from one of two areas:

How we manage apps

While Zendesk offers a full way to manage apps 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 and managed content repos.

Administrator tasks

Versioning

For Zendesk app version, you use the following style:

Major.Minor

This follows Semantic Versioning (without the Patch number). As such, you should combine the normal Minor and Patch definitions into one.

As a general rule:

  • Minor version changes (increment Minor number):
    • Bug fixes and corrections
    • Small UI improvements
    • Performance optimizations
    • Minor feature additions
  • Major version changes (increment Major, reset Minor to 0):
    • Breaking changes to functionality
    • Major redesigns or rewrites
    • Significant new features
    • Changes requiring new permissions

As an example:

  • doing small changes on app version 2.9 would make the new version 2.10
  • doing large changes on app version 2.9 would make the new version 3.0

Installing an app

To install an app in Zendesk, you first must package your app. To do this, run the following command (via CLI) within the project repo:

zip -r data/application.zip assets manifest.json translations

You will then use data/application.zip to upload (and install) the app in Zendesk by doing the following:

  1. Navigate to the admin dashboard for the Zendesk instance
  2. Go to Apps and integrations > Apps > Zendesk Support apps
  3. Click Upload private app in the top-right of the page
  4. Enter the app’s name (as it is detailed in the app’s manifest.json file)
  5. Click Choose File and select the data/application.zip file made previously
  6. Click Upload

From there, you will be taken to the app’s page (after install), where you can set the restrictions, parameters, etc.

Updating an app

Updating already installed apps is considerably easier since a corresponding sync repo controls it. To update an app, you will need to create a MR in the sync repo for the app. The exact changes being made will depend on the request itself.

After a peer reviews and approves your MR, you can merge the MR. When the next deployment occurs, it will be synced to Zendesk.

Force updating an installed app in the sandbox

If you need to force update an app in the sandbox (especially during development), run the command ./bin/sync_sandbox force when within the project repo (via CLI).

Deactivating an app

To deactivate an app:

  1. Navigate to the admin dashboard for the Zendesk instance
  2. Go to Apps and integrations > Apps > Zendesk Support apps
  3. Hover over the app in question and click the down arrow
  4. Click the slider under the Enabled option

Uninstalling an app

To uninstall an app:

  1. Navigate to the admin dashboard for the Zendesk instance
  2. Go to Apps and integrations > Apps > Zendesk Support apps
  3. Hover over the app in question and click the down arrow
  4. Click Uninstall

Performing an exception deployment

To perform an exception deployment for an app, navigate to the app 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 app.

Common issues and troubleshooting

Not seeing app changes after a merge

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

App development
Documentation on Zendesk app development
Global apps
Documentation on Zendesk Global apps
US Government apps
Documentation on Zendesk US Government apps
Last modified January 21, 2026: Revamp CustSuppOps handbook (7d49549f)
View page source - Edit this page - please contribute. Creative Commons License