How Git-Zen Works

Git-Zen is an integration app that connects your Zendesk support tickets to your engineering work. It supports GitHub, GitLab, Linear, Azure DevOps, and Jira. It also has newer integrations for Trello, ClickUp, Notion, monday.com, and Asana. See Other integrations.

Git-Zen keeps your Zendesk agents and workflow separate from your development work. At the same time, it keeps the two in sync.

A Zendesk agent uses the ticket sidebar to create or link an issue or work item when a ticket needs engineering work. Git-Zen then keeps the ticket in sync as the work moves through your workflow. A developer works in the issue or work item to resolve the ticket. On GitHub, GitLab, and Azure DevOps, a developer can also reference Zendesk tickets in commit messages. Zendesk then shows which files changed to address the ticket.

Git-Zen internal communication

Git-Zen has two parts:

The application that you see in your Zendesk ticket screen.
A webhook that sends events from your platform back to Git-Zen.

When you create an issue or work item from the Git-Zen app, or link an existing one, Git-Zen talks directly to your platform. It uses the credentials of the OAuth user who set up Git-Zen to create or change the item.

When an issue, work item, or commit is added or changed, the webhook sends this information to Git-Zen. If the item contains a Git-Zen reference tag in its text, Git-Zen updates the Zendesk ticket with information about the issue, work item, or commit. Git-Zen also stores a summary of the linked items in a ticket custom field named Git-Zen_data, which it creates during installation. Do not delete or edit this field.

You need one webhook for each GitHub repository. See the GitHub OAuth user.

User identities

Git-Zen must act as an authenticated user when it works in Zendesk or in your platform. It uses the identity of the user who completed the initial setup. Any action Git-Zen takes, such as adding a comment, uses that user’s credentials.

On Linear

Git-Zen for Linear works like the other platforms, with these differences:

Teams take the place of repositories. Linear organizes work into teams, for example Engineering with the key ENG. In Git-Zen, a Linear team takes the place of a repository or project.
Workflow states instead of open and closed. Linear issues move through the workflow states that each team defines. Git-Zen treats a state of type completed or canceled as “closed”. See Workflow states.
One assignee per issue. Git-Zen uses the first assignee you choose.
One webhook for the whole workspace. You do not set up a webhook for each team.
No commits. Linear does not host code. Git-Zen does not link commits or show affected files for Linear.
Full version only. There is no Lite version of Git-Zen for Linear. See Plans, Trial and Billing.

Git-Zen talks to Linear through Linear’s GraphQL API. It uses the credentials of the Linear OAuth user to create and change issues.

Git-Zen finds the Zendesk tickets for an issue by the reference tag in the issue description. A gz# tag in a comment does not link the issue.

Events that reach Zendesk

When Linear sends an event for an issue with a reference tag, Git-Zen adds a comment to each linked ticket:

Issue created, updated, or removed. The comment shows the team, the issue, who made the change, the labels, the state, and the priority. For these changes, it also says what changed: workflow state, assignee, labels, priority, title, project, and cycle. Other changes show as Issue updated.
Comment added, edited, or deleted. Git-Zen copies the comment text to the ticket. It converts Linear Markdown to HTML.

Issue events also update the issue details that the Git-Zen sidebar shows on the ticket. For the settings that control these comments, see Ticket comments: incoming.

Tokens

Linear access tokens expire after 24 hours. Git-Zen renews the token for you with a refresh token. You need to re-authorize only if someone revokes the Git-Zen authorization in Linear, or if the authorizing user leaves the workspace. See Linear OAuth user.

Need more help?

To set up Git-Zen, see the quick start on the home page. If you need extra help, or think the documentation is missing something, contact us at support@git-zen.com.