Gitlab linking to external issue tracker does not work, but test connection is successfull

by

Summary

A user configured GitLab’s Custom Issue Tracker integration, received a Connection Successful test response, but found that #ID references in commits and comments did not link to the external tracker. The issue was caused by a misconfigured Issue URL pattern that did not properly interpolate the Issue ID parameter, resulting in GitLab generating invalid links that the external tracker redirected to a generic home page, masking the failure.

Root Cause

The primary cause was an incorrectly formatted Issue URL template in GitLab’s integration settings.

  • Incorrect Interpolation: The user input #!/details/:id. GitLab’s Custom Issue Tracker integration requires the token %{id} (or :id in specific legacy contexts) to be dynamically replaced by the actual issue number. If the token is missing or malformed, GitLab generates a static URL or one that fails to pass the ID.
  • Silent Failure via Redirection: The external issue tracker was configured to redirect invalid or unparseable URLs to the home page (#!/home). Since the generated GitLab link did not correctly contain the issue number, the tracker treated it as an invalid request and redirected. This made the links appear to “go somewhere” (the home page) rather than throwing an HTTP error, confusing the diagnosis.
  • Legacy Parameter Deprecation: The user attempted to use the <project>-<id> syntax. This syntax is deprecated or specific to legacy integrations and does not apply to the standard GitLab Custom Issue Tracker section, which relies on URL patterns rather than project keywords.

Why This Happens in Real Systems

In enterprise environments, we often integrate GitLab with internal, proprietary issue trackers (like Jira, Azure DevOps, or custom ASP.NET applications).

  1. Ambiguous Documentation: GitLab’s documentation lists multiple integration methods (Jira native, Custom Issue Tracker, external wiki). The “Custom Issue Tracker” section often lacks explicit examples for Single Page Applications (SPAs) using hash routing (e.g., #!/), leading engineers to assume the URL structure maps 1:1.
  2. Defensive UX Design: External trackers (especially corporate ones) are often designed to be “user-friendly.” They catch 404s or invalid parameters and redirect to a dashboard instead of returning a hard 404 Not Found. This hides integration errors from end-users but breaks automated testing and developer workflows.

Real-World Impact

  • Broken Traceability: Developers reference issues in commit messages (e.g., “Fixes #1810”), but the hyperlinks are non-functional. This breaks the audit trail and Code Review context.
  • Reduced Adoption: Teams lose trust in the integration and revert to manual copy-pasting of URLs, reducing workflow efficiency.
  • False Confidence: The “Test Settings” button passing creates a false sense of security. The test usually only validates network connectivity or authentication, not the regex accuracy of the URL pattern generation.

Example or Code

To verify the integration is working, you must inspect the generated URL. You can use a simple script to simulate how GitLab constructs the link.

# Simulating GitLab's Custom Issue Tracker URL interpolation
# In a real scenario, GitLab uses Ruby's % {} syntax for formatting.

def generate_issue_url(base_url, issue_id)
  # GitLab expects '%{id}' in the Custom Issue Tracker settings
  # to be replaced by the actual issue number.
  #
  # INCORRECT (User's configuration likely looked like this):
  # url = "https://path/to/issue_tracker/index.aspx#!/details/:id"
  # Result: https://path/to/issue_tracker/index.aspx#!/details/:id (Static string, broken)

  # CORRECT (Required format):
  # The field must contain '%{id}'
  formatted_url = base_url % { id: issue_id }
  return formatted_url
end

# Configuration from the user's problem
# Note the '%{id}' placeholder
project_url = "https://path/to/issue_tracker/app/index.aspx#!/home"
issue_url_pattern = "https://spath/to/issue_tracker/index.aspx#!/details/%{id}"

# Generate link for issue #1810
generated_link = generate_issue_url(issue_url_pattern, 1810)

puts "Generated Link: #{generated_link}"
# Expected Output: https://spath/to/issue_tracker/index.aspx#!/details/1810

How Senior Engineers Fix It

  1. Verify the Token Syntax: Senior engineers recognize that GitLab’s Custom Issue Tracker (unlike the native Jira integration) strictly requires the %{id} formatted string. They update the Issue URL field to explicitly include this token:
    https://path/to/issue_tracker/index.aspx#!/details/%{id}
  2. Inspect Network Traffic: Instead of relying on UI feedback, they open the Browser Developer Tools (F12) Network tab. They look for the request generated when clicking a #ID reference. If the URL redirects to the home page, they check the “Location” header in the response to see where the external tracker sent them.
  3. Test via Direct URL Construction: They manually construct the URL in the browser address bar using the pattern https://path/to/issue_tracker/index.aspx#!/details/1810 to confirm the external tracker actually supports that deep link structure.
  4. Check GitLab Rails Console (Self-Managed): If the instance is self-managed, they may check the integration validity via the console (ApplicationSetting.last.custom_issue_tracker_url) to ensure the database has accepted the update.

Why Juniors Miss It

  • Over-reliance on “Test Connection”: Juniors interpret the “Connection Successful” message as “My links will work.” They fail to realize the test only checks if GitLab can reach the host, not if the URL path is constructed correctly.
  • Syntax Confusion: Assuming that any placeholder (like :id or <id>) will work. GitLab Custom Issue Tracker is specific to the %{id} Ruby interpolation format.
  • Debugging Blindly: When clicking a link and landing on the home page, they assume the link “partially works” rather than investigating why the ID was stripped or ignored. They miss the HTTP 302 Redirect logic that signals the external app rejected the input.