Git-Zen for Azure DevOps Installation and Usage

Power User QuickStart Installation

  1. Install the Git-Zen app from the Zendesk marketplace
  2. Open any ticket
  3. Locate Git-Zen in the "Apps" sidebar
  4. Click "Authorize"
  5. "Allow" Zendesk access
  6. "Accept" Azure DevOps access
  7. Refresh entire Zendesk browser window

IMPORTANT: You MUST refresh the entire browser window that is currently running Zendesk; do not click simply click the "reload all apps" button, as this will re-start the authorization process


How to use Git-Zen for Azure DevOps

To associate a Azure DevOps commit or work item, all you have to do is include the Zendesk ticket number in a Azure DevOps commit comment or for Azure DevOps work item description, prefaced by "gz#"; in the below example, the Zendesk ticket number is 12345:

this is a comment for gz#12345

You may add more than one ticket number in the same commit (or work item) comment; both tickets will have the commit (or work item) added to it in Git-Zen.

gz#12345 and gz#67890 were affected by this commit

You may add commits from different repositories to the same ticket; this is especially useful when a solution to a ticket is spread across multiple projects, such as a when a change is required to both a database schema and a web application in order to solve an work item.


Installation Walkthrough

Git-Zen installation is quick and easy; Git-Zen will step you through the process. Git-Zen requires two different access points in order to function:

  1. Access to your Zendesk tickets
  2. Access to your Azure DevOps repositories

Once the Git-Zen application is installed in Zendesk, open any Zendesk ticket. Then, open the "Apps" sidebar. The Git-Zen application should be visible. You will be directed to begin the authorization process:

Git-Zen pre-authorization

Git-Zen pre-authorization

When you click "Authorize", a separate window will open requesting access to your Zendesk account; this is accomplished through a Zendesk OAUTH token (which can be revoked at any time in your Zendesk user account "security" settings tab). If you are not logged in to Zendesk, you will be asked to log in at this point.

Zendesk authorization

Zendesk authorization

After clicking "Allow" on the Zendesk authorization screen, you will be taken to the authorization screen for your Azure DevOps repositories. If you are not logged in to Azure DevOps, you will be asked to log in here.

Azure DevOps authorization

Azure DevOps authorization

Once you authorize Git-Zen to access Azure DevOps, the authorization window will close. Return to your Zendesk window, and refresh the Zendesk window. IMPORTANT: You MUST refresh the entire browser window that is currently running Zendesk; do not click simply click the "reload all apps" button, as this will re-start the authorization process.

You should now see the full Git-Zen application in the app sidebar. There will be a "settings" menu option visible:

Azure DevOps menu

Git-Zen Settings

In the settings menu, scroll to the bottom, and you will see a place for your Organization Name. This name is used by Git-Zen to communication to your Azure DevOps organization, and it is important to enter it before you proceed further:

Azure DevOps menu

Azure DevOps menu

After setting your organziation name that is used in Azure DevOps, click "Save Changes".

From the main screen, there will be visible a "Webhooks" icon on the Git-Zen menu bar.

Azure DevOps menu

Azure DevOps menu

Click this icon to view your available Azure DevOps projects for your organization, and select which projects you wish to have active for Git-Zen. Then, click the "Save Changes" button.

link Azure DevOps

link Azure DevOps

Git-Zen is ready to use!


Using Git-Zen without authorizing Azure DevOps (optional)

If you do not wish to authorize Git-Zen to access your Azure DevOps repositories automatically, you can still use Git-Zen by adding webhooks manually to your Azure DevOps repostories. To do this, you will need your webhook URL from the Git-Zen menu.

IMPORTANT: Git-Zen cannot create Azure DevOps work items without oAuth access; if you manually create webhooks, you can still link Azure DevOps work items by adding a "gz#" comment in the work item comments, but you cannot create an work item directly from the Zendesk application.

First, complete the above steps (including the Zendesk authorization), but close the window when you are asked to authorize Azure DevOps. Then, refresh your Zendesk browser window. Click on the "Webhooks" menu at the top of the Git-Zen application:

Azure DevOps menu

Azure DevOps menu

On the subsequent settings screen, find the section titled "Manual Azure DevOps Configuration". This section will have a unique webhook URL for you to use.

Azure DevOps webhook

Azure DevOps webhook

Copy this URL to your clipboard, and then follow these steps:

  1. Sign in to Azure DevOps, then select the desired project
  2. Go to Project Settings > Service Hooks
  3. Select "Create Subscription"
  4. On the "Trigger" screen, select event "Code pushed"
  5. On the "Action" screen, paste the URL copied from Git-Zen
  6. No other headers or authentication is required, click "Finish"
  7. Repeat these steps for "Work item commented", "Work item created", "Work item deleted", and "Work item updated"

For more information about adding webhooks to Azure DevOps, please see the Microsoft documentation regarding webhooks.

Repeat these steps for each repository that you wish to use with Git-Zen. The same URL is used for every repository.