Provide granular feedback for SSH signature verification failures

Problem

SSH signature verification currently returns a generic :unverified status for multiple failure scenarios, making it difficult for users to understand why their signed commits aren't showing as verified.

Unlike GPG signatures, which distinguish between different email-related failures, SSH signatures fail silently to "Unverified" when the committer email doesn't match a verified email address.

Current SSH Verification Statuses

From lib/gitlab/ssh/signature.rb:

def calculate_verification_status
  return :unknown_key unless signed_by_key
  return :other_user unless committer?
  return :unverified unless signed_by_user_email_verified?
  
  :verified
end

The :unverified status is returned for:

  • Invalid signature blob (line 30)
  • Email not in verified emails (line 85)
  • Missing attributes (line 28)

GPG Comparison

GPG signatures provide more granular feedback in lib/gitlab/gpg/signature.rb:

if gpg_key.verified_and_belongs_to_email?(email)
  :verified
elsif gpg_key.user.all_emails.include?(email)
  :same_user_different_email
else
  :other_user
end

This allows users to distinguish between:

  • :verified - Email is verified and belongs to the key owner
  • :same_user_different_email - Email belongs to the user but isn't verified (actionable feedback)
  • :other_user - Email belongs to a different user

Proposal

Add a :same_user_different_email verification status for SSH signatures to match GPG behavior.

Suggested Implementation

Modify calculate_verification_status in lib/gitlab/ssh/signature.rb:

def calculate_verification_status
  return :unknown_key unless signed_by_key
  return :other_user unless committer?
  return :same_user_different_email unless signed_by_user_email_verified?
  
  :verified
end

def signed_by_user_email_verified?
  signed_by_key.user.verified_emails.include?(committer_email)
end

This would require:

  1. Adding :same_user_different_email to the SSH signature verification status enum
  2. Updating the UI to display appropriate messaging for this status
  3. Updating documentation to reflect the new status

Benefits

  1. Clearer user feedback: Users can immediately identify that they need to verify their email address
  2. Consistency: SSH and GPG signature verification provide the same level of detail
  3. Better debugging: Easier to troubleshoot signature verification issues

Related

  • !217363 (merged) - Documentation clarification that prompted this issue
  • #584734 - Original issue about unclear commit email requirements
Edited by 🤖 GitLab Bot 🤖