GitLab with YouTrack, Linear or ClickUp issues

How a GitLab issue tracker integration keeps issues outside GitLab

A team may keep its planning in YouTrack, Linear, Bugzilla or ClickUp while its code, merge requests and pipelines live in self-managed GitLab. GitLab bridges the two through its documented project integrations: commits and merge requests that reference an external issue key can be linked back to that issue, so the tracker stays the system where work is planned and prioritized. GitLab's native external tracker integrations cover Bugzilla, ClickUp, Engineering Workflow Management, Linear, Phorge, Redmine and YouTrack. For any other tracker, the custom issue tracker option lets you point GitLab at an external tracker through URL patterns you define. The work is therefore configuration plus two decisions: which tracker is the source of truth, and whether issues are created and closed in that tracker or in GitLab.

The second decision drives most of the configuration effort. If issues are created in the external tracker, GitLab only needs to recognize its issue references and display links to them, and the team must agree on the reference format so developers write keys that GitLab can match. If the team also wants merge requests to close external issues automatically, confirm in the integration documentation for that specific tracker whether closing is supported and which keywords trigger it, since this varies by integration. Do not assume that a native integration offers every behavior of the custom option. Before enabling anything in production, run a test project and confirm that a commit message and a merge request description each produce the expected link, and that the link opens the correct item in the tracker. Review the GitLab project integrations documentation for the exact settings each tracker needs.

Plan the operating model before rollout. Someone must own the integration settings, the reference format conventions and the answer to what happens when a tracker is migrated, renamed or retired. Integrations can be configured at instance or group level and inherited by projects, so a shared setting for a tracker can be defined once and overridden where a project needs a different tracker. Confirm with your administrators which integrations are allowed on the instance, because an allowlist can prevent teams from enabling a tracker that the security or compliance owners have not approved. Keep a short record of the tracker, the reference format and the owner for each project so that issue links remain accurate as teams change.

What you need before enabling an external tracker

Most failed tracker integrations trace back to a gap in access, edition or network path, not to the GitLab setting itself. The five items below are the checks to close before anyone opens an integration page, and each one maps to a person or system you need to involve.

Confirm edition and version

Check the GitLab edition and version your instance runs, then confirm in the integrations documentation that the tracker you want is offered on that tier and version. Tier availability is set by GitLab and can change between releases, so do not rely on memory or a comparison table. Record the result with the instance version so the configuration can be reviewed during the next upgrade stop.

Administrator access for instance settings

Instance-level integration defaults can only be set by someone with administrator rights on the self-managed instance. Confirm which named administrator will own the change, and whether the team wants an instance default that projects inherit or a per-project setup. Without this owner, configuration tends to stall at the first setting that needs an instance administrator.

Group owner for group settings

Where integrations are set at group level, the group owner must agree to the values and must be able to apply them to the projects beneath. Identify the owner of each group that will hold GitLab projects linked to the tracker. Inheritance then flows down, so a group owner who is unaware of the change can be surprised by new issue links on existing merge requests.

Tracker account with read and reference rights

Create or designate a tracker account that can read issues and resolve issue keys referenced in commits and merge requests. Confirm with the tracker vendor which permission set is needed for each product and whether the account can be a service account. Also confirm the API access method and token policy for that product, including token expiry and rotation, because these rules differ between YouTrack, Linear, Bugzilla and ClickUp.

Network path from GitLab to the tracker

GitLab must reach the tracker URL over HTTPS from the instance and any runner that reads the links. In restricted or air-gapped networks, confirm the outbound proxy, firewall rule or private network path, and whether the tracker certificate is trusted by the GitLab host. Test reachability from the GitLab server itself, since a browser test from a workstation does not prove the integration can connect.

Native trackers or the custom issue tracker option

Choose the native YouTrack integration when engineers already plan work in YouTrack and want commits and merge requests to reference those issues without moving them into GitLab. YouTrack is on GitLab's list of external issue tracker integrations, so the setup happens in GitLab's integration settings and does not require custom code.

Project URL and reference pattern: Confirm the project URL and issue reference format that GitLab expects for YouTrack, then test it with a sample commit message in a sandbox project.
Authentication: Confirm which credential GitLab needs to reach YouTrack and which account owns it, because that account's permissions decide what links and details appear.
Level of configuration: Decide whether to set the integration at instance, group or project level, and confirm which projects will inherit it.
Version compatibility: Confirm that the integration and its options are supported on the GitLab version you run, since integration options can change between releases.
Issue ownership: Confirm that issues stay in YouTrack and that the team agrees on which system is the source of truth for status.

Before enabling the integration, ask the YouTrack administrator to confirm project keys, permissions and the workflow states your teams use.

Configuring the tracker at instance, group and project level

This sequence sets the external tracker once where it belongs, lets projects inherit it, and confirms each level behaves as intended before teams rely on issue references in commits and merge requests.

Confirm the tracker choice against the docs
The platform team checks the tracker against the GitLab project integrations documentation before any configuration. That page lists the external issue trackers GitLab supports natively, which currently include Bugzilla, ClickUp, Linear and YouTrack, along with a custom issue tracker option for other systems. Confirm the integration name, the required connection details and any tier or version notes for your GitLab release. Record the chosen tracker and its owner in your change log. The step closes when the team can name the integration and list the connection values it needs from the tracker administrator.
Prepare credentials and a test issue in the tracker
The tracker administrator creates a service account or API credential with the narrowest permissions that allow reading issues and linking references, then creates one disposable test issue in a non-production project. Store the credential in your secrets process, not in a shared document. Confirm with the tracker vendor which token type and URL format it expects, because these differ between products. The step closes when the test issue has a known identifier and the credential has been verified with a direct API call from a network location that can reach both systems.
Configure the integration at instance level
A GitLab administrator opens the instance-level integration settings and enters the tracker URL, project identifier pattern and credentials, then enables the integration as the default for the instance. Use this level only when most or all projects should send references to the same tracker. Field names and screens come from the GitLab documentation for your version, so follow that page rather than assumptions. The step closes when the instance setting saves without error and the administrator can see the integration listed as active at the instance level.
Set or override the integration at group level
A group owner opens the group integration settings to either accept the inherited instance values or set group-specific values, such as a different tracker URL or project mapping for one business unit. Keep the number of overrides small so that ownership stays clear. Document which groups override the default and why. The step closes when the group settings page shows the expected source for each value, with inherited fields marked as inherited and overridden fields showing the group value.
Override at project level where needed
A project maintainer changes the integration only when a project must use a different tracker or a different setting from its group, for example a project that tracks work in Linear while its group uses YouTrack. Record each project-level override in the project's documentation so that future group changes do not surprise the team. The step closes when the project's integration page shows the intended tracker and the override is listed in the team's register of exceptions.
Test with a throwaway branch and reference
A maintainer creates a throwaway branch in a test project, commits a message that references the disposable tracker issue, and opens a merge request with a similar reference in its title or description. The check passes when the tracker issue shows a link back to the commit or merge request, and the link resolves to the correct tracker instance. Repeat the test in one project that inherits from the group and one that overrides it, because inheritance errors often appear only in the second case. Delete the test branch and issue afterward. The step closes when both inherited and overridden projects produce correct links.
Review inheritance after each change
Whenever the instance or a group changes the tracker setting, the administrator reviews the projects that inherit it and confirms that overrides still apply as intended. Schedule this check as part of your change process and repeat the test reference after any change to credentials, tracker URLs or project key formats. Confirm with the tracker vendor whether its API version or authentication method is changing, since that affects the saved credentials. The step closes when the review record lists the projects checked and the test result for each.

Which GitLab objects and tracker fields link to each other

This table maps each place where GitLab and an external tracker meet, from commit messages and branch names to the default tracker set at instance or group level. It shows who should decide each mapping and what to confirm in the integration docs before rollout. Read it as a checklist: the mismatches that cause broken links usually come from identifiers that were never agreed.

Mapping rule	What it controls	Owner of the decision	What to confirm in the docs
Issue keys in commit messages	Whether a commit referencing a tracker key appears on the external issue, and which key format the tracker expects	Project maintainers, with the platform team setting the pattern	The exact reference format the chosen tracker's integration accepts and whether commits are linked automatically
Issue keys in branch names	Whether a branch created for an issue carries the tracker key into merge request and pipeline views	Project maintainers	Whether the branch naming pattern is matched by the integration, and how it treats case and separators
Issue keys in merge request titles	Whether a merge request is linked to the tracker item it resolves, and whether merging can update the item	Project maintainers and the tracker administrator	Whether merge request titles are scanned for keys and which workflow transitions, if any, the integration can trigger
Tracker issue keys and URLs	The address GitLab uses to build links back to the external item and to recognize references	Platform team	The URL and key format required by YouTrack, Linear, Bugzilla or ClickUp in the integration settings
Default tracker at instance level	The integration values every project inherits unless overridden	Platform team	Which integration fields can be inherited and which must be set per project
Default tracker at group level	The tracker shared by all projects in a group, and the override path for individual projects	Group owners, with the platform team approving	Whether a project can disable or replace an inherited tracker and how overrides appear in settings
Tracker project or team identifier	The container in the tracker (project, team, workspace or component) that receives issues from a GitLab project	Tracker administrator	The identifier type each tracker requires and that it matches the GitLab project mapping exactly
Ownership of mapping changes	Who may rename projects, change keys or move repositories without breaking links	Platform team and project maintainers together	Whether renaming a GitLab project or a tracker project changes stored links, and how to re-point them

How instance and group settings decide what each project inherits

Set the tracker default at the highest level that fits, then let projects inherit it. GitLab integrations can be configured at instance level or group level, and projects inherit those settings unless someone overrides them. For a YouTrack, Linear, Bugzilla or ClickUp tracker, this means a project can start pointing at the right tracker without anyone opening its integration settings. Before you write the default, confirm in the GitLab Docs: Project integrations page which level each external tracker supports, and whether inheritance behaves the same way for every tracker you plan to use. Do not assume that a setting valid for one tracker carries over to the others. A project-level override wins over the group default. That is useful when one team uses a different tracker, but it also means the group default stops describing that project. Expect a few overrides over time, and record them in your own governance notes, because a project that quietly differs from its group is easy to miss during an audit of where issues live. Also check what happens to inherited values when a project is moved between groups or when a group is renamed or moved. Test this on a non-production group first, confirm the resulting settings and the tracker links in merge requests and commits, and only then plan the rename or move for production. Decide one default tracker per group before creating many projects. Each new project created under a group picks up that group's configuration, so a wrong default multiplies across every new repository, and correcting it later means finding and reviewing each project. Write the group-to-tracker mapping down, name the owner who approves changes to it, and confirm the inheritance behavior for each tracker in the docs before rolling it out to all groups.

Securing tracker credentials and access in the integration

An external tracker integration gives GitLab a credential, a network path and a set of permissions into another system. Five controls keep that link narrow: who holds the credential, who can change the settings, what the account can reach, which network routes are open, and which integrations administrators allow in the first place.

Store the tracker credential with least rights

The integration stores a token or account that GitLab uses to read and reference issues in the tracker. Ask the tracker which token types it offers and grant only the read and reference permissions the links need. Name a rotation owner before go-live, record the expiry date, and plan how the credential is replaced without breaking merge request references. A shared admin token that never expires is the most common gap to close.

Restrict who changes integration settings

Instance and group integration settings decide where credentials are entered and which projects inherit them. Limit changes to a small set of administrators and group owners, and review that list when roles change. A group owner who edits an inherited setting changes it for every project below that group, so treat group-level edits as a change to all of its projects.

Confirm the tracker account sees only what it should

Check the tracker account's project and workspace membership before connecting it. The account should reach only the projects whose issues GitLab commits and merge requests reference. Test with a sample reference from a restricted project and confirm that the link view does not expose titles or fields from projects the team should not see. Repeat the check after any role change in the tracker.

Review outbound paths in restricted networks

GitLab calls the tracker's API over HTTPS from the instance, so the tracker host must be reachable from the GitLab network. In restricted or offline environments, confirm the route, the proxy rules and the allowed destinations with your network team, and check the GitLab hardening guidance on outbound requests before opening any path. Self-hosted trackers on internal addresses may need an explicit allowance, which should be reviewed rather than broadly opened.

Limit which integrations administrators allow

An integration allowlist controls which integration types can be enabled on the instance. Keep only the trackers your organization has approved, such as YouTrack or Linear, and leave others off so that a project owner cannot connect an unreviewed service. Confirm the list with your security team, record it with the integration design, and review it when a new tracker is requested.

Why issue links stop appearing after the integration is enabled

This table pairs each common symptom with its likely cause and a check to run, so you can narrow down why references are not linking to an external tracker. Work through the rows in order, since the connection and inheritance checks usually come before pattern and reference checks. Each fix is a starting point to verify in your own instance, not a guaranteed result.

Symptom	Likely cause	Check or fix to run
Issue references in commits or merge requests do not link	The integration is disabled for the project, or the tracker's issue reference pattern does not match the key format used in your tracker	Confirm the integration is active on the project. Compare a sample key, such as the one your tracker issues, with the pattern the integration expects, and test with a commit message that contains a known key.
Links appear on some projects but not others	A project overrides the group or instance setting, or the project never inherited the integration	Open the integration settings on each project and compare them with the group and instance values. Reset the project to inherit where the override is unintended, then recheck a sample project.
Tracker connection test fails with an error	The tracker URL is wrong, the GitLab instance cannot reach it over the network path, or the credential has expired or lacks permission to read issues	Confirm the base URL includes the correct scheme and host. Test reachability from the GitLab host, including any proxy or firewall rules. Generate a new credential under a service account with read access to the relevant projects.
Links point to the wrong tracker after a group change	The group was moved or re-pointed to a different integration, and projects still carry an older override or cached setting	Review the group integration and each affected project. Remove stale overrides, then check that a test reference resolves to the expected tracker URL.
References work with one tracker but not the custom issue tracker option	The custom pattern or URL template does not match the project key format, or the regular expression has a syntax issue	Test the pattern against sample references from your tracker outside GitLab. Correct the expression and the URL template, then retest with a new commit or merge request.
Links show up in merge requests but not in commits	The reference was added to a commit message on a branch that never reached the default branch, or the pattern differs between link locations	Confirm the commit appears in the branch used for the test. Check the same reference in a merge request description and a commit message to see which location fails.

What does a tracker integration cost and how long does it take

Does GitLab charge separately for external issue tracker integrations?

Confirm this on the GitLab pricing page for the tier your instance runs, because the answer depends on the edition you hold rather than on the tracker itself. The pricing page lists Free, Premium and Ultimate as available for self-managed installations, and the tracker integrations sit in the project and group integration settings of the instance. Check the current feature list against your edition before you budget, and ask your GitLab account contact to confirm that the specific tracker you plan to use is available on your tier. Any licence fees for the tracker product itself, such as YouTrack, Linear, Bugzilla or ClickUp, are separate and are set by that vendor.

What makes a tracker integration take more effort?

Effort grows with the number of trackers, the number of groups that need their own settings, and whether you use the custom issue tracker option for a tool GitLab does not support natively. Network path matters as well: a tracker reachable only through a proxy, an internal DNS name or a restricted segment needs firewall and certificate work before any test can pass. Testing scope adds time, since you need to confirm how issue references, links and closing keywords behave in commits and merge requests. Identity and token handling also add work, because each integration needs credentials owned by a named account with the right permissions in the tracker.

Can our own team set up a tracker integration without a partner?

Yes, for a single native tracker with a clear owner on each side, an administrator with access to the instance settings can usually configure it internally. The work is mostly settings, a test project and a few verification steps, so a team that already runs GitLab administration can handle it. The picture changes with the custom issue tracker option, which needs you to define the URLs, issue patterns and link formats yourself and test them against real data. It also changes when several groups need different defaults, or when the tracker sits behind a network path that only your security team can change. Those cases benefit from a written scope, even if your team does the build.

What does the team need to provide before integration work starts?

The work needs four things from your side. First, an administrator who can change instance and group integration settings. Second, a tracker owner who knows the project keys, workflow states and how issues are created and closed. Third, a test project in GitLab and a test workspace or project in the tracker, so changes can be verified without touching live issues. Fourth, a written decision on issue ownership: whether issues stay in the external tracker, whether new work is opened there, and which system is the record for status. Agreeing the fourth point early prevents rework, because the link format and the closing behavior depend on it.

How does the work change if issues move into GitLab later?

Moving issues into GitLab is a separate migration project, not a reversal of the integration. The external tracker settings can stay in place while you import, but the team must decide which issues move, which are closed in the old tracker and which links to keep. GitLab documents importing Jira issues and FogBugz issues, but other trackers need their own export and mapping work, and you should confirm what your tracker can export before you commit to a date. Plan for a period where references point to both systems, and record which system is authoritative for each project so developers know where to look.

What should a fixed-scope tracker integration record in writing?

A fixed-scope engagement should state the trackers in scope, the instance and group levels where settings apply, and which projects inherit them. It should list the integration settings to be configured, the network paths and credentials involved, and the test cases used to verify issue links, closing behavior and access. It should name the responsibilities on both sides, including who owns the tracker account and who approves changes to the allowlist. The document should also record the handover items: a settings summary, the runbook for rotating credentials, and the open items your team must confirm with the tracker vendor. DeployOpen gives a quote from that written scope, and we do not publish a price list.

What recurring work follows a tracker integration?

After go-live, the recurring work is operational rather than build work. Credentials used for the tracker connection need rotation under your identity policy, and the tracker account must keep the permissions it needs after staff changes. Each GitLab upgrade should include a check that the integration still behaves as expected, since integration settings and supported options can change between releases. Tracker product upgrades can also change APIs or URL formats, so ask the tracker owner to notify the GitLab administrator before a planned change. Budget for this as an ongoing task owned by a named administrator, whether your team or a retainer covers it.

How DeployOpen scopes and delivers tracker integrations

DeployOpen plans, builds, documents and supports self-hosted GitLab inside your own infrastructure, including the tracker integrations that keep issues in YouTrack, Linear, Bugzilla or ClickUp while code stays in GitLab. Each engagement starts from a written scope, so the tracker choice, the instance or group settings and the handover are agreed before any configuration begins.

How we scope

Confirm which external tracker each group and project uses, and whether the custom issue tracker option is needed.
Record whether settings live at instance level, group level or per project, and who may override them.
Agree in writing which integration allowlist rules, credentials and reference formats are in scope.

How we build

Configure the chosen tracker integration at instance or group level, then test inheritance on sample projects.
Verify issue links, commit references and merge request references resolve to the correct tracker items.
Document each credential, its owner and the rotation steps before anything moves to production projects.

How we hand over

Deliver a configuration record listing every integration, its scope level and any project overrides.
Walk your administrators through enabling, disabling and troubleshooting integrations on the GitLab instance.
Provide a test checklist your team can rerun after GitLab upgrades or tracker changes.

How we support

Ongoing support, upgrades and testing are available as a retainer once the handover is complete.
Retainers can cover review of integration changes when GitLab releases or tracker APIs change.
Confirm with the tracker vendor which API versions and plans your organization needs before the engagement starts.

GitLab with YouTrack, Linear, Bugzilla or ClickUp issue trackers