Clarify that URL uniqueness applies to stored identifiers

GitLab payloads do carry an instance-global id, but it was never
persisted; only the URL is stored on every record. Reword the migration
note and mark gitlab_id as unsafe for lookups.

Author: akabiru

db/migrate/20260608120000_add_unique_index_to_integration_html_urls.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-# The webhook URL is the only globally unique identifier for a pull request,
-# merge request or issue: per-project sequential numbers (GitLab's iid) repeat
-# across repositories. Enforce that uniqueness at the database level so a
-# missed lookup site or a concurrent webhook can never split one entity across
-# two rows. Surviving duplicates are folded into the most recent row first;
+# The webhook URL is the only globally unique identifier stored for a pull
+# request, merge request or issue: GitLab records hold only the per-project
+# iid, which repeats across repositories, and GitHub records created from
+# comment payloads carry no github_id at all. Enforce the URL's uniqueness at
+# the database level so a missed lookup site or a concurrent webhook can never
+# split one entity across two rows. Surviving duplicates are folded into the most recent row first;
 # none are expected, since every write path already keys on the URL.
 class AddUniqueIndexToIntegrationHtmlUrls < ActiveRecord::Migration[8.1]
   disable_ddl_transaction!

modules/gitlab_integration/app/models/gitlab_issue.rb

@@ -55,6 +55,8 @@ class GitlabIssue < ApplicationRecord
   def self.find_by_gitlab_identifiers(url:, id: nil, initialize: false)
     raise ArgumentError, "needs an url" if url.blank?
 
+    # gitlab_id holds GitLab's per-project iid, which repeats across
+    # repositories, so the URL is the only identifier safe to look up by.
     found = find_by(gitlab_html_url: url)
     found || (new(gitlab_id: id, gitlab_html_url: url) if initialize)
   end

modules/gitlab_integration/app/models/gitlab_merge_request.rb

@@ -58,6 +58,8 @@ class GitlabMergeRequest < ApplicationRecord
   def self.find_by_gitlab_identifiers(url:, id: nil, initialize: false)
     raise ArgumentError, "needs an url" if url.blank?
 
+    # gitlab_id holds GitLab's per-project iid, which repeats across
+    # repositories, so the URL is the only identifier safe to look up by.
     found = find_by(gitlab_html_url: url)
     found || (new(gitlab_id: id, gitlab_html_url: url) if initialize)
   end