How Zammad shows GitLab issue status in the ticket sidebar
Many support teams spend part of every working day asking engineering whether a bug behind a customer ticket has been picked up, who owns it and whether it is close to a fix. Zammad's GitLab integration addresses this by linking GitLab issues to tickets and showing the issue's status, assignee and labels in a sidebar tab on the ticket. Agents can read that information without leaving Zammad or posting a question in an engineering channel. The integration covers GitLab issues only, so the plan you make for it should start from that boundary. The integration needs a GitLab token with the read_api permission. That scope lets Zammad read issue data, which is what the sidebar displays. Decide which account owns the token before setup. A dedicated service account is easier to audit and rotate than a personal token, and it keeps the integration working when the person who created it changes roles. Ask your GitLab administrators to confirm that the account can see the projects support needs and nothing it should not. Record who holds the token, where it is stored and how it will be replaced when it expires or is revoked. The integration does not support merge requests. Agents will see the status of the linked issue, but they will not see whether a merge request for that issue is open, approved or merged. If support leads expect to answer "is the fix deployed yet?" from the sidebar, that answer will need another source, such as a release note or a direct message from the engineer responsible. Write this limit into the support runbook so agents do not assume a missing status means no code has been written. The supplied facts cover GitLab only. Do not plan a GitHub issue sidebar on the basis of this section. Before you commit to GitHub, confirm with Zammad what its GitHub issue linking supports, including the fields shown in the ticket and the token permissions it requires. Then, for a GitLab rollout, check the token on your own instance, link one test issue to a test ticket, confirm the sidebar fields display as expected and confirm the self-managed GitLab endpoint setting matches your server.
What you need before linking GitLab issues to Zammad
The integration depends on four things meeting in one place: a Zammad instance you control, a GitLab account with read access to the right projects, a read-only token, and a network path from Zammad to the GitLab API. Confirm each item before configuration so that the sidebar in Zammad shows the issue data you expect from the start.
A running Zammad instance you control
The GitLab integration is configured inside your own Zammad installation, so the instance must already be deployed, reachable by your agents and under your administration. Confirm the Zammad version you run against the Zammad admin documentation before you start, because integration options and settings can change between releases. Decide which group of agents will use the issue sidebar, since that shapes who needs to see linked data.
Admin access to Zammad
Adding the GitLab integration and entering the token requires an administrator role in Zammad, so plan which person or team holds that access. Agents who only work tickets will see the linked issue tab once an administrator has configured it, but they cannot set it up themselves. Record who made the change and when, because the token is a credential that will need rotation later.
A GitLab account that can read target projects
The integration reads issue data through the GitLab account whose token you supply, so that account determines which projects appear in Zammad. Whether you run GitLab as SaaS or self-managed, confirm the account is a member of every project whose issues support staff need to see. Projects the account cannot read will return no data, which looks like a broken link rather than a permissions gap.
A token with read_api permission
The GitLab integration needs a token with the read_api scope. Create a dedicated token for this integration rather than reusing a personal token from an engineer, so it can be rotated or revoked without affecting other tools. Store the token in your secret management process, and confirm the expiry date and owner in your credential register.
Outbound network reach to the GitLab API
Zammad must call the GitLab API endpoint over HTTPS, so the server running Zammad needs an outbound route through any proxy or firewall you operate. For self-managed GitLab, the endpoint is your own hostname, which must resolve and present a certificate that Zammad trusts. Test the path from the Zammad host itself, not from an engineer's workstation, because egress rules often differ between them.
Scope limits to agree with support leads
The integration shows issue status, assignee and labels, but it does not support merge requests. If support staff expect to see code review state or linked branches, record that gap before rollout so the expectation is set. Also confirm the version of GitLab you run against the GitLab documentation, since the API surface the integration depends on follows the version you operate.
Choosing a GitLab account and token scope for the link
Link Zammad to GitLab with a dedicated service account, not a personal token from a developer or team lead. A token is tied to the account that created it, so a personal token stops working when that person leaves, changes role or loses access to a project, and the ticket sidebar goes silent without warning. A service account created for support linking keeps the integration independent of individual staff changes, and the GitLab audit trail shows the integration as its own identity. Before you create the token, confirm with GitLab's authentication and authorization documentation how token expiry and rotation work on the GitLab tier you run, including who can set and renew expiry and whether your tier enforces limits on token lifetime. Write that schedule into your runbook before go-live. The Zammad GitLab integration needs a token with the read_api permission. That is the documented permission for this link, and it is the one to request. The trade-off is that read_api is broader than the three fields the sidebar displays. Through the API, a token with this permission can read project data beyond issue status, assignee and labels, including issue content and other project metadata the account is allowed to see. Zammad does not narrow that exposure for you, so the protection has to come from the GitLab side. Treat read_api as a read-wide permission and assume that anything the account can read through the API may be reachable by anyone who obtains the token. Because the token inherits the account's access, scope the link by project membership. Create the service account, then add it only to the projects whose issues support staff need to see in tickets. Keep the role as low as the integration works with, and do not add the account to groups that contain unrelated or sensitive repositories, since group membership often grants access to every project beneath it. Check how private projects and confidential issues appear to this account in a test before you rely on the link. Also decide who owns the account, because the person who handles project access requests will need to review that membership whenever a project moves in or out of support's scope. A practical sequence is to create the service account, add it to one test project, generate a read_api token, enter it in Zammad, and confirm that a linked ticket shows status, assignee and labels for that project only. Then repeat the check for a project the account should not see and confirm that nothing appears. Record the token owner, its expiry date and the membership list in your configuration records. Schedule a review of membership each time support takes on a new project, and treat any change in the GitLab tier or authentication settings as a reason to recheck the token lifecycle.
Configuring the GitLab link in Zammad step by step
This sequence connects one Zammad instance to one GitLab source using a dedicated account and a read-only token, then proves the link with a test ticket before agents rely on it. The result is a GitLab tab in the ticket sidebar that shows each linked issue's status, assignee and labels.
Create a dedicated GitLab service account
Ask your GitLab administrator to create a separate user account that belongs to the Zammad integration. Use a separate account so token activity stays attributable and survives staff changes. Grant it membership only in the projects whose issues support agents need to see, and confirm with the administrator which role is enough to read issue status, assignee and labels. Check that the account can open one of those issues in a browser and cannot open issues from projects it should not see.
Create a token with read_api scope
Signed in as the service account, create a personal access token and select only the read_api scope, which the Zammad GitLab integration requires. Set an expiry date that your team can rotate on a schedule. Store the token value in your secrets manager at once, because GitLab displays it only once. If you link GitHub instead, the token type and scopes differ, so confirm them in the Zammad admin documentation for your installed version. The check: the token appears in the account's token list with read_api as its only scope.
Record the GitLab API endpoint
Write down the base URL the integration will call. For GitLab SaaS, this is the public GitLab host. For self-managed GitLab, use the URL of your instance as the Zammad server can reach it, and confirm the API path with your GitLab administrator. If your instance uses an internal certificate authority, confirm that the Zammad server trusts it before you continue. The check: a test API request from the Zammad application server, using the token, returns a valid response and not a network or certificate error.
Enter the endpoint and token in Zammad
Sign in to Zammad as an administrator and open the GitLab integration settings in the admin area. The exact menu path depends on the installed version, so take it from the Zammad admin documentation for that version. Enter the endpoint and the token, enable the integration and save. Keep the token out of shared notes and tickets. The check: the settings save without a validation error and the integration shows as enabled.
Confirm the connection is working
Use the connection test in the integration settings if your Zammad version provides one, or review the application log for the first request the integration makes. A working connection shows no authentication or permission error. Common causes of failure are an expired token, a token without read_api, a mistyped endpoint path, and a Zammad server that cannot reach the GitLab host through the firewall or proxy. The check: the integration reports a successful connection and the log contains no authorization errors for the service account.
Link a test issue to a test ticket
Create a test ticket in a test group or queue that agents do not use for live customer work. Link it to a known test issue in a GitLab project the service account can read. Use the issue link function on the ticket as the Zammad admin documentation describes for your version. The check: the link is saved on the ticket, and the issue reference is still visible after you reload the page.
Check status, assignee and labels in the sidebar
Open the linked test ticket and find the GitLab tab in the sidebar. Compare the status, assignee and labels shown there with the GitLab issue. Then change one value in GitLab, such as a label, and confirm the sidebar reflects it. Confirm with your Zammad version how often updates arrive. Also check that merge requests do not appear, because the integration does not support them. The check: the sidebar matches the issue, and the change in GitLab appears in Zammad within the update interval you confirmed.
Which GitLab fields appear in the Zammad ticket sidebar
This table lists which GitLab issue fields the Zammad GitLab tab displays, who owns each value, and whether agents can change it from the sidebar. Read it before promising support staff that a ticket will reflect GitLab state. The main takeaway is that status, assignee and labels are the documented fields, and merge requests are not supported at all.
| Field | Shown in the sidebar | Value owned by | Editable from the sidebar |
|---|---|---|---|
| Status | Yes. The current status of the linked GitLab issue appears in the GitLab tab on the ticket, so agents see progress without leaving Zammad. | GitLab | Not documented as editable. Confirm in the Zammad admin documentation before telling agents they can change it. |
| Assignee | Yes. The GitLab user assigned to the linked issue appears in the GitLab tab, which helps support see which engineer owns the fix. | GitLab | Not documented as editable. Confirm in the Zammad admin documentation and test with a sample issue. |
| Labels | Yes. The GitLab labels applied to the linked issue appear in the GitLab tab, so triage labels such as severity or product area are visible to agents. | GitLab | Not documented as editable. Confirm in the Zammad admin documentation and test with a sample issue. |
| Merge requests | No. Merge requests are not supported by the Zammad GitLab integration, so none appear in the sidebar. Support teams need another way to check code review or deployment state. | Not applicable | Not applicable. Plan support workflows that check merge request state directly in GitLab. |
| Other GitLab fields | Not part of the documented mapping. Do not assume that milestones, due dates, comments or other issue attributes appear in the sidebar. | GitLab | Confirm each field in the Zammad admin documentation before building support procedures around it. |
| Zammad ticket fields | Ticket state, priority and agent assignment are Zammad fields. They are managed on the ticket itself and are separate from the values shown in the GitLab tab. | Zammad | Managed in Zammad ticket fields, not in the GitLab tab. Keep the two sets of values distinct in training. |
Pointing Zammad at a self-managed GitLab endpoint
Many organizations that link Zammad to GitLab run GitLab on their own servers, in a private data center, or in a network with no direct internet access. In those cases the integration only works if the Zammad host can reach the GitLab instance directly, and the first decision is the instance URL. Enter the exact base address that your GitLab installation serves, including the scheme, host name and any relative path. A host name that resolves differently for users on the corporate network than for the Zammad application server is a common cause of failed connections, so confirm name resolution from the Zammad host itself rather than from a workstation.
Next, confirm the network path. Zammad makes outbound HTTPS requests to the GitLab API, so the firewall rules, proxy settings and any load balancer in front of GitLab must allow traffic from the Zammad application nodes on the port GitLab listens on. Test this from the same host, the same network segment and, where Zammad runs in containers, from inside the container network. A successful test from an administrator laptop proves very little. Also check that any egress proxy your organization requires is configured for the Zammad host, since Zammad does not inherit the proxy settings you use for browsers.
Internal certificate authorities are the step most often missed. If GitLab presents a certificate issued by a private CA, the Zammad host must trust that CA chain at the operating system level and in the runtime Zammad uses. Users may already accept the certificate because their browsers import the corporate root, which hides the gap. Ask your PKI or platform team for the full chain, including any intermediate certificates, and verify it with a request from the Zammad host before you save the integration settings. Do not disable certificate verification to get the link working, because that removes the protection the token relies on.
Finally, verify that the GitLab API is reachable from the Zammad host and not only from users' browsers. The integration needs a GitLab token with read_api permission, and Zammad must call the API itself to read issue status, assignee and labels for the sidebar. Plan a test that uses the same token and endpoint Zammad will use, and confirm the response includes the issue data you expect. Also confirm the token scope and owner with your GitLab administrator, because the token's access determines which issues appear to agents. For how your restricted network should be designed, including package delivery and other offline needs, use GitLab's offline environments documentation as the reference and confirm the details with your GitLab administrators. The Zammad GitLab link itself does not carry a documented offline support statement, so do not assume it is supported in an air-gapped setup without testing it in your own environment.
Hardening the GitLab token and link
The GitLab or GitHub link gives Zammad read access to issue data through a token, so the token, the account behind it and the network path it uses carry the risk. The controls below cover who holds the credential, what it can reach, where it is stored, how it changes over time and how the integration is watched.
Dedicated service account
Create a separate GitLab user for the Zammad integration instead of tying the token to a person's account. If the employee leaves or changes role, the integration keeps working and its access stays visible as a single identity in the GitLab audit trail. Confirm with GitLab's authentication documentation how service accounts and their tokens are created and managed on your edition and version.
Least-privilege project membership
Add the service account only to the projects whose issues support staff need to see, with the lowest role that still lets it read those issues. The Zammad link needs a token with read_api permission, so the token itself should not be broadly scoped beyond that need. Review membership on a schedule, because projects added later can silently widen what Zammad can read.
Token storage in Zammad admin settings
Enter the token only in the GitLab integration settings in Zammad, and do not paste it into tickets, macros, shared notes, chat or configuration files kept in version control. Restrict the admin role that can open these settings to a short named list, since anyone who can view the integration may be able to read or replace the credential. Check how your Zammad version displays stored secrets before assuming they are masked.
Token rotation on staff changes
Define a rotation trigger tied to HR and admin changes: whenever someone who created, configured or could read the token leaves or changes role, issue a new token and retire the old one. Plan the cut-over so that support is not left without issue status during the switch. Ask your team to record the rotation date and the owner of the token, because the token expiry and owner are the first facts an auditor or incident responder will ask for.
Logging and reviewing integration edits
Record who can change the GitLab integration in Zammad, including the endpoint, token and linked projects, and review those changes on a regular cadence. Zammad's own admin activity and your log platform are the places to check, so confirm what each records before relying on it. Pair the review with the GitLab audit events for the service account to spot unexpected project access or token use.
Egress limited to the GitLab endpoint
Allow the Zammad host to reach only the GitLab endpoint it needs, whether that is GitLab.com or your self-managed hostname, over HTTPS. Block other outbound destinations at the firewall or proxy so a compromised Zammad host cannot send the token elsewhere. If your GitLab runs on a private network or in an air-gapped setup, confirm the exact host and port with your GitLab administrator before writing the rule.
Keeping the link working through GitLab upgrades
The Zammad GitLab integration reads issue data through the GitLab API using a token with read_api permission, so any GitLab upgrade can change the conditions the link depends on. Plan a re-test after every GitLab upgrade step, not only after the ones that look large. The test should confirm two things: that the sidebar tab still shows status, assignee and labels for a known issue, and that the stored token still authenticates against the self-managed GitLab endpoint Zammad points to. Record the GitLab version, the Zammad version and the result each time, so a later failure can be traced to a specific change. Because the integration does not support merge requests, the test should use issues only.
GitLab requires upgrades to pass through required upgrade stops. Since GitLab 17.5, these fall at versions x.2, x.5, x.8 and x.11, for example 18.2, 18.5, 18.8, 18.11, 19.2, 19.5, 19.8 and 19.11. A team moving between stops may need to pass through each one in order, so the sidebar and token test belongs at each stop, not only at the final version. Check the GitLab upgrade paths documentation for the exact sequence before scheduling work, because the stops are the required checkpoints and your path may include additional steps between them. Confirm with your own team which Zammad release is paired with each GitLab version on the path.
GitLab ships a major release once a year, with GitLab 20.0 planned for May 2027. Minor releases arrive on the third Thursday of each month, and patch releases come twice a month. That cadence means a self-managed instance can receive several GitLab changes in a single quarter. The re-test should be built into the standing change process and repeated each cycle. Decide who owns the test, who approves a version change, and what happens when the test fails. Confirm current release dates on the GitLab maintenance policy page, because the schedule is the source to check, not this page.
The maintenance policy also affects how long an instance can safely run behind the current release. GitLab backports bug fixes only to the current stable release, while security fixes are also backported to the previous two monthly releases. An instance that lags by a few monthly releases may still receive security fixes but no longer receive bug fixes for behavior the Zammad link relies on. Set a limit on how far behind the current release the instance may run, and schedule upgrades so the gap stays within it. This page does not state whether any particular GitLab version breaks the Zammad link. Check the Zammad admin documentation for the GitLab integration and run the re-test on your own instance.
Why GitLab issues do not appear in Zammad tickets
This table lists the usual reasons a linked GitLab issue fails to show in the Zammad ticket sidebar, the check each one needs and the fix. Work down the list in order, because token and endpoint problems cause most failures. Confirm the cause in the Zammad and GitLab logs for the versions you have installed before changing settings, since log messages vary between releases. Merge requests are not supported, so a merge request link will never display.
| Likely cause | What the admin checks | Fix |
|---|---|---|
| Token lacks read_api | Token scopes in GitLab do not include read_api | Create a token with read_api and save it in the Zammad GitLab settings. |
| Endpoint URL is wrong | Host name points to another instance or omits the scheme | Enter the full address of the instance that holds the project, including https://. |
| Certificate not trusted | Self-managed GitLab uses a certificate that Zammad cannot verify | Install the internal certificate authority on the Zammad host, then retest the connection. |
| Firewall blocks Zammad | Outbound HTTPS from the Zammad host to the GitLab address is denied | Allow the Zammad host to reach the GitLab address on its HTTPS port. |
| Account cannot see project | The token owner is not a member of the project | Add the token owner to the project with access to the issues, then retest. |
| Item is a merge request | The linked item is a merge request, which the integration does not support | Link the related issue instead. Merge requests will not appear in the sidebar. |
| Link made to wrong issue | The ticket points to another project path or issue number | Check the project path and issue number in the ticket link, then relink the correct issue. |
Questions teams ask before linking GitLab to Zammad
Does the Zammad GitLab link also work with GitHub?
GitHub support is not confirmed for this plan, so check it with Zammad before you plan anything around it. The GitLab integration is the documented option for this link. Ask Zammad whether an issue link to GitHub exists for your Zammad version, which fields the ticket sidebar would show, which token permissions it needs and whether it works with your setup. Until you have that answer in writing, keep GitHub out of the scope and the budget. If your issues sit in both systems, plan and test the GitLab link first, then treat GitHub as a separate question with its own confirmation step and its own test.
Do merge requests appear in Zammad tickets with the GitLab link?
No. The Zammad GitLab integration links issues to tickets and does not support merge requests. A ticket shows the linked issue's status, assignee and labels in the sidebar, but not merge request state, reviewers or pipeline results. Support staff who need to know whether a fix has shipped will have to read the linked issue or ask engineering. Design the support workflow around issues from the start, and write down which engineering signals agents will still need to check elsewhere. If merge request visibility matters to your team, raise it as a requirement before the build, since it changes scope and testing. Confirm the current position with Zammad first.
What does the GitLab link cost in effort, and what drives it?
Effort depends on your environment more than on the integration itself. The main drivers are token and endpoint setup, which means a GitLab token with read_api permission pointed at the correct instance. Network and certificate work adds effort when GitLab is self-managed on a private address, sits behind a proxy or uses a certificate from an internal authority. Testing across each project you link also adds effort, because projects differ in permissions and labels. Re-testing after Zammad and GitLab upgrades recurs over the life of the link. The first three items are mostly one-time work. Upgrade re-tests and token rotation recur. Ask any quote to split setup from recurring checks and to name the projects and instances in scope.
How long does it take to set up a GitLab link in Zammad?
No duration is set here, so ask for one in writing against your agreed scope. Several things lengthen a setup: an unclear GitLab endpoint, a self-managed instance behind a VPN or proxy, certificate chains from an internal authority, many projects that each need checking, a slow approval process for the token owner, and a sidebar review involving several stakeholders who each want a say. A single instance, a supported endpoint, a test project ready on day one and admin access in place all shorten the work. Ask the provider to list the dependencies it expects you to clear before the build starts, because those are usually what moves the timeline.
Can our own team link GitLab to Zammad without a partner?
Yes, for a single Zammad instance connected to a supported GitLab endpoint, a capable administrator can do it by following the Zammad admin documentation. The work is mostly configuration: create a token with read_api permission, enter the endpoint, link a test project and check the sidebar. A partner adds the most value in self-managed networks, certificate handling, multiple instances, testing across many projects and upgrade re-tests. If your team has not yet handled Zammad upgrades or GitLab token policy under your security rules, review the steps with the named owner before you start. That review reduces rework and surprises later.
Is the GitLab link priced separately from the Zammad rollout?
No. The GitLab link is priced as part of a wider Zammad rollout quote, based on your written scope. Zammad self-hosted has no license fee, according to Zammad's pricing page. Its optional self-hosted support subscriptions are Business at 2,999 EUR per year, Enterprise at 5,999 EUR per year and Corporation at 9,999 EUR per year, with response times of 6, 4 and 2 hours respectively. Ask which tier fits your needs and whether support covers issues that arise from the link. The subscription is paid to Zammad, and the services work is quoted separately from your written scope.
What must our team provide before the GitLab link work starts?
Four things. First, a named owner who answers scope questions and signs off on changes. Second, GitLab admin access, so the team can create or approve a token and see the projects in scope. Third, a test project that is safe to link and has labels similar to your production projects. Fourth, a written sign-off on who sees what in the ticket sidebar, since status, assignee and labels can reveal internal work to agents in other groups. Agree on the GitLab instance and the projects in scope as well. Missing any one of these usually moves the timeline more than the cost.
Which GitLab token permissions does the Zammad link need?
The integration needs a GitLab token with read_api permission. Use a dedicated service account token for it. A personal token ties the link to one employee and stops working when that person leaves or changes role. Record the token owner, the expiry date and the rotation process in your secrets register. Confirm the current token options with GitLab's documentation, since settings can change between releases. Keep the scope to read_api unless Zammad's admin documentation names another permission for a feature you want. Check the token against a test project before you link production projects, and retest after any GitLab upgrade.
How DeployOpen scopes and supports the GitLab link
DeployOpen approaches the Zammad and GitLab or GitHub link as one part of a self-hosted helpdesk, planned inside your own infrastructure. We confirm which GitLab instance, token scope and projects the link will use before any build starts. Engagements are fixed-scope, with the written scope defining what is built, tested and documented.
How we scope
- Confirm whether the GitLab instance is self-managed and record its exact base endpoint in the scope.
- Record the read_api token scope, the owning account and which projects will link to Zammad tickets.
- Write down that merge requests are out of scope, so agents know the sidebar covers issues only.
How we build
- Configure the GitLab integration in a staging Zammad instance before touching production tickets.
- Test the sidebar with sample issues covering status, assignee and label display for each agent group.
- Check network routes from Zammad to the self-managed GitLab endpoint, including any proxy or private DNS.
How we hand over
- Document the token rotation steps, owner, expiry handling and the scopes granted to the integration.
- Provide a runbook for re-linking projects, troubleshooting missing sidebar data and updating the endpoint.
- Hand over a written list of known limits, including the absence of merge request support.
How we support
- Offer ongoing support and upgrades as a retainer, scoped in writing alongside the initial build.
- Re-test the link after Zammad or GitLab upgrades, since each platform moves on its own release schedule.
- Check GitLab required upgrade stops before moving versions, and confirm the token still works afterward.
