GitLab: Field-Sync
Full Version Only.
Git-Zen can keep fields in step between Zendesk tickets and linked GitLab issues. Sync works in both directions:
- Zendesk → GitLab: a ticket change updates the linked GitLab issues. For example, ticket tags become GitLab labels.
- GitLab → Zendesk: an issue change updates the linked tickets. For example, GitLab labels become ticket tags.
You set up each sync rule as a mapping under Field Mappings in the settings. See Tag/label pairs for the full setup steps. This page covers GitLab field names and behavior. For the GitLab events that post ticket comments, see What syncs from GitLab.
Zendesk → GitLab fields
Section titled “Zendesk → GitLab fields”Use these GitLab field names in a mapping with the direction To GitLab →:
| GitLab field | Value | Notes |
|---|---|---|
labels |
label names, comma-separated | With Append, Git-Zen adds to the issue’s labels. Without it, Git-Zen replaces them. |
state or status |
open or closed |
Git-Zen converts the value to GitLab’s state_event (reopen or close). |
state_event |
close or reopen |
Sent to GitLab as is. |
assignee_ids |
numeric GitLab user IDs, comma-separated | GitLab IDs, not user names. |
milestone_id |
numeric milestone ID | Use the ID, not the title. 0 removes the milestone. |
weight |
whole number | GitLab Premium and Ultimate. A value that is not a number becomes 0. |
due_date |
YYYY-MM-DD |
|
title |
text | Replaces the title. |
description |
text | Replaces the whole description, including the gz# reference tag. Use with care. |
Git-Zen sends any other field name to the GitLab Edit issue API as a text value. GitLab ignores names it does not know.
GitLab → Zendesk fields
Section titled “GitLab → Zendesk fields”Use these GitLab field names in a mapping with the direction ← From GitLab:
| GitLab field | Value sent to Zendesk |
|---|---|
state or status |
open or closed |
id or number |
the issue number (IID) |
label or labels |
the label names, as a list |
assignees |
the assignee user names, as a list |
url |
the issue URL |
title |
the issue title |
updated |
the last update date, as YYYY-MM-DD |
Git-Zen does not sync milestone, weight, or due date from GitLab to Zendesk fields. The sidebar still shows them, and Git-Zen can comment when they change.
For the Zendesk side, use tags, status, priority, or a custom field ID. Git-Zen updates a custom field only if the field exists on the ticket. For status, the value must be a Zendesk status: new, open, pending, hold, solved, or closed. To send closed as solved, add a character replacement in the mapping’s Advanced Options.
When sync runs
Section titled “When sync runs”Zendesk → GitLab runs when a ticket update fires the Git-Zen trigger in Zendesk. Git-Zen reads the changed fields and updates every GitLab issue linked to the ticket. A ticket can have issues in several projects. Git-Zen updates each one.
GitLab → Zendesk runs when the GitLab webhook sends an Issues event, for example when you edit, label, close, or reopen an issue.
If one ticket has many linked issues, Git-Zen may stop part of the way through a single update to stay within its time limit. The next ticket update syncs the rest.
Conflicts
Section titled “Conflicts”The last change wins. A Zendesk change overwrites the GitLab value. A later GitLab change overwrites the Zendesk value. To make one side the source of truth for a field, map that field in one direction only.
Common mappings
Section titled “Common mappings”| Zendesk field | Direction | GitLab field | Use case |
|---|---|---|---|
tags |
→ | labels |
Send ticket tags to GitLab labels |
tags |
← | labels |
Bring GitLab labels back as ticket tags |
| custom field ID | ← | number |
Show the issue number in a ticket field |
| custom field ID | ← | state |
Show the issue state in a ticket field |
| custom “Release” field | → | milestone_id |
Set the milestone from a ticket field that holds the milestone ID |
To close the GitLab issue when you solve the ticket, map status → state. In Advanced Options, add a character replacement that turns solved into closed.
Troubleshooting
Section titled “Troubleshooting”My mapping is set up, but GitLab does not change. Check that the mapping’s direction slider shows To GitLab →. Check that the OAuth user can edit the issue. GitLab rejects changes from users with the Guest role.
The value in GitLab is wrong or empty. Check the value format in the table above. For example, milestone_id and assignee_ids need numeric IDs.
My weight mapping does nothing. Weight needs GitLab Premium or Ultimate.
A GitLab change does not reach Zendesk. Check that the project’s webhook sends Issues events. Also check the field name in the GitLab → Zendesk table above.