From 5187c8ac28a501d8a4fec7100c0b0633baacd0f2 Mon Sep 17 00:00:00 2001
From: michaelangeloio <arivera@gitlab.com>
Date: Sun, 30 Nov 2025 14:09:14 -0500
Subject: [PATCH] feat: add project contributors panel feature

This commit introduces a new feature to track and display project contributors, including their commit counts. Key changes include:

- Creation of a `project_contributors` table to store contributor statistics.
- Implementation of methods to fetch contributors from the repository and cache their data.
- Updates to the user interface to display contributors in a GitHub-style panel.
- Enhancements to the Gitaly client for listing contributors.
- Addition of tests to ensure functionality and data integrity.

This feature aims to improve visibility into project contributions and enhance user engagement with contributor statistics.
---
 Gemfile                                       |   3 +-
 Gemfile.lock                                  |  10 +-
 app/assets/javascripts/user_popovers.js       |   3 +-
 .../components/user_popover/user_popover.vue  |   8 +
 app/helpers/projects_helper.rb                |  22 ++
 app/models/projects/contributor.rb            | 123 ++++++++++
 app/models/repository.rb                      |  18 ++
 app/services/git/branch_hooks_service.rb      |   5 +
 .../projects/_contributors_panel.html.haml    |  67 ++++++
 app/views/projects/_sidebar.html.haml         |   3 +
 app/workers/all_queues.yml                    |  10 +
 .../projects/contributors_cache_worker.rb     |  36 +++
 db/docs/project_contributors.yml              |  13 ++
 ...51129180216_create_project_contributors.rb |  27 +++
 ...217_add_project_contributors_project_fk.rb |  17 ++
 db/schema_migrations/20251129180216           |   1 +
 db/schema_migrations/20251129180217           |   1 +
 db/structure.sql                              | 221 +++++++++++++-----
 lib/gitlab/git/repository.rb                  |  16 ++
 lib/gitlab/gitaly_client/commit_service.rb    |  62 +++++
 locale/gitlab.pot                             |  11 +
 spec/factories/project_contributors.rb        |  10 +
 .../gitaly_client/commit_service_spec.rb      |  74 ++++++
 spec/models/projects/contributor_spec.rb      |  95 ++++++++
 24 files changed, 798 insertions(+), 58 deletions(-)
 create mode 100644 app/models/projects/contributor.rb
 create mode 100644 app/views/projects/_contributors_panel.html.haml
 create mode 100644 app/workers/projects/contributors_cache_worker.rb
 create mode 100644 db/docs/project_contributors.yml
 create mode 100644 db/migrate/20251129180216_create_project_contributors.rb
 create mode 100644 db/migrate/20251129180217_add_project_contributors_project_fk.rb
 create mode 100644 db/schema_migrations/20251129180216
 create mode 100644 db/schema_migrations/20251129180217
 create mode 100644 spec/factories/project_contributors.rb
 create mode 100644 spec/models/projects/contributor_spec.rb

diff --git a/Gemfile b/Gemfile
index 52bfd45efa3082..75c4e52a4c70c2 100644
--- a/Gemfile
+++ b/Gemfile
@@ -634,7 +634,8 @@ gem 'ssh_data', '~> 2.0', feature_category: :shared
 gem 'spamcheck', '~> 1.3.0', feature_category: :insider_threat
 
 # Gitaly GRPC protocol definitions
-gem 'gitaly', '~> 18.6.0', feature_category: :gitaly
+# Using local gitaly gem for ListContributors RPC development
+gem 'gitaly', path: '../gitaly/_build/gitaly', feature_category: :gitaly
 
 # KAS GRPC protocol definitions
 gem 'gitlab-kas-grpc', '~> 18.5.0-rc4', feature_category: :deployment_management
diff --git a/Gemfile.lock b/Gemfile.lock
index b430d961ddfc19..24323b37095567 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,3 +1,9 @@
+PATH
+  remote: ../gitaly/_build/gitaly
+  specs:
+    gitaly (18.6.0.pre.fa577c21b)
+      grpc (~> 1.0)
+
 PATH
   remote: gems/activerecord-gitlab
   specs:
@@ -732,8 +738,6 @@ GEM
     git (1.19.1)
       addressable (~> 2.8)
       rchardet (~> 1.8)
-    gitaly (18.6.0)
-      grpc (~> 1.0)
     gitlab (4.19.0)
       httparty (~> 0.20)
       terminal-table (>= 1.5.1)
@@ -2175,7 +2179,7 @@ DEPENDENCIES
   gettext (~> 3.5, >= 3.5.1)
   gettext_i18n_rails (~> 1.13.0)
   git (~> 1.8)
-  gitaly (~> 18.6.0)
+  gitaly!
   gitlab-active-context!
   gitlab-backup-cli!
   gitlab-chronic (~> 0.10.5)
diff --git a/app/assets/javascripts/user_popovers.js b/app/assets/javascripts/user_popovers.js
index b9dcb097c849d0..8aeb916e511012 100644
--- a/app/assets/javascripts/user_popovers.js
+++ b/app/assets/javascripts/user_popovers.js
@@ -13,7 +13,7 @@ const removeTitle = (el) => {
 
 const getPreloadedUserInfo = (dataset) => {
   const userId = dataset.user || dataset.userId;
-  const { username, name, avatarUrl, email } = dataset;
+  const { username, name, avatarUrl, email, commitCountText } = dataset;
 
   return {
     userId,
@@ -21,6 +21,7 @@ const getPreloadedUserInfo = (dataset) => {
     name,
     avatarUrl,
     email,
+    commitCountText,
   };
 };
 
diff --git a/app/assets/javascripts/vue_shared/components/user_popover/user_popover.vue b/app/assets/javascripts/vue_shared/components/user_popover/user_popover.vue
index b2756fc248353d..d7069aabce0b89 100644
--- a/app/assets/javascripts/vue_shared/components/user_popover/user_popover.vue
+++ b/app/assets/javascripts/vue_shared/components/user_popover/user_popover.vue
@@ -275,6 +275,14 @@ export default {
       <template v-else>
         <template v-if="!isBlocked">
           <div class="gl-text-subtle">
+            <div
+              v-if="user.commitCountText"
+              class="gl-mb-2 gl-flex"
+              data-testid="user-popover-commit-count"
+            >
+              <gl-icon name="commit" class="gl-shrink-0" />
+              <span class="gl-ml-2">{{ user.commitCountText }}</span>
+            </div>
             <div v-if="user.email" class="gl-mb-2 gl-flex">
               <gl-icon name="mail" class="gl-shrink-0" />
               <span ref="email" class="gl-ml-2">{{ user.email }}</span>
diff --git a/app/helpers/projects_helper.rb b/app/helpers/projects_helper.rb
index 64139bc2615aa4..666ab58af2b0d5 100644
--- a/app/helpers/projects_helper.rb
+++ b/app/helpers/projects_helper.rb
@@ -1054,6 +1054,28 @@ def delete_inactive_projects?
       ::Gitlab::CurrentSettings.delete_inactive_projects?
     end
   end
+
+  # Returns contributors for the project contributors panel.
+  # Fetches from database only - data is populated by background worker on push.
+  #
+  # @param project [Project] the project to get contributors for
+  # @param branch [String, nil] the branch to get contributors for (nil for default branch)
+  # @param limit [Integer, nil] maximum number of contributors to return (nil for all)
+  # @return [Array<Hash>] array of contributor hashes with :email, :commits keys
+  def project_contributors(project, branch: nil, limit: nil)
+    branch_key = branch.presence || project.default_branch || Projects::Contributor::ALL_BRANCHES
+
+    contributors = Projects::Contributor.for_project_branch(
+      project.id,
+      branch: branch_key,
+      limit: limit
+    )
+
+    contributors.map { |c| { email: c.email, commits: c.commits } }
+  rescue StandardError => e
+    Gitlab::ErrorTracking.track_exception(e, project_id: project.id)
+    []
+  end
 end
 
 ProjectsHelper.prepend_mod_with('ProjectsHelper')
diff --git a/app/models/projects/contributor.rb b/app/models/projects/contributor.rb
new file mode 100644
index 00000000000000..04f6669409048a
--- /dev/null
+++ b/app/models/projects/contributor.rb
@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Projects
+  class Contributor < ApplicationRecord
+    self.table_name = 'project_contributors'
+
+    # Special branch name used to store aggregated stats across all branches
+    ALL_BRANCHES = '__all__'
+
+    DEFAULT_LIMIT = 100
+
+    BATCH_SIZE = 1000
+
+    belongs_to :project
+
+    validates :project, presence: true
+    validates :branch, presence: true, length: { maximum: 1024 }
+    validates :email, presence: true, length: { maximum: 1024 }
+    validates :commits, presence: true, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    validates :email,
+      uniqueness: { scope: [:project_id, :branch], message: 'already exists for this project and branch' }
+
+    scope :for_project, ->(project_id) { where(project_id: project_id) }
+    scope :for_branch, ->(branch) { where(branch: branch) }
+    scope :by_commits, -> { order(commits: :desc) }
+    scope :by_email, -> { order(:email) }
+
+    # Returns contributors for a project and branch, ordered by the specified field
+    #
+    # @param project_id [Integer] the project ID
+    # @param branch [String] the branch name (use ALL_BRANCHES for all branches aggregated)
+    # @param order [Symbol] :commits or :email
+    # @param limit [Integer, nil] maximum number of contributors to return (nil for all)
+    # @return [ActiveRecord::Relation]
+    def self.for_project_branch(project_id, branch:, order: :commits, limit: DEFAULT_LIMIT)
+      relation = for_project(project_id).for_branch(branch)
+
+      relation = case order
+                 when :email
+                   relation.by_email
+                 else
+                   relation.by_commits
+                 end
+
+      limit ? relation.limit(limit) : relation
+    end
+
+    # Refreshes contributor data for a project from the repository.
+    # Called by the worker after push events. Stores ALL contributors.
+    #
+    # @param project [Project] the project to refresh
+    # @param branch [String, nil] specific branch or nil for all-branches aggregate
+    def self.refresh_from_repository(project, branch: nil)
+      return unless project.repository.exists?
+      return if project.repository.empty?
+
+      branch_key = branch.presence || ALL_BRANCHES
+
+      contributors_data = project.repository.all_contributors(
+        ref: branch,
+        order: :commits,
+        contributor_type: :author
+      )
+
+      update_for_project_branch(project.id, branch_key, contributors_data)
+    rescue StandardError => e
+      Gitlab::ErrorTracking.track_exception(e, project_id: project.id, branch: branch_key)
+    end
+
+    # Updates contributor records for a project and branch.
+    # Stores ALL contributors using upsert to efficiently update commit counts.
+    #
+    # @param project_id [Integer] the project ID
+    # @param branch_key [String] the branch name or ALL_BRANCHES
+    # @param contributors_data [Array<Hash>] contributor data from repository
+    def self.update_for_project_branch(project_id, branch_key, contributors_data)
+      return if contributors_data.blank?
+
+      current_time = Time.current
+
+      # Aggregate by email - same person may appear with different names
+      # Sum commits for duplicates
+      deduplicated = contributors_data
+        .group_by { |c| c[:email].to_s.downcase.truncate(1024) }
+        .map do |email, entries|
+          total_commits = entries.sum { |e| e[:commits].to_i }
+          {
+            email: email,
+            commits: total_commits
+          }
+        end
+
+      incoming_emails = deduplicated.map { |c| c[:email].to_s.downcase.truncate(1024) }
+
+      transaction do
+        # Remove contributors no longer in the repository
+        where(project_id: project_id, branch: branch_key)
+          .where.not(email: incoming_emails)
+          .delete_all
+
+        # Upsert contributors in batches (insert or update commit count)
+        deduplicated.each_slice(BATCH_SIZE) do |batch|
+          records = batch.map do |contributor|
+            {
+              project_id: project_id,
+              branch: branch_key,
+              email: contributor[:email].to_s.downcase.truncate(1024),
+              commits: contributor[:commits].to_i,
+              created_at: current_time,
+              updated_at: current_time
+            }
+          end
+
+          upsert_all(
+            records,
+            unique_by: [:project_id, :branch, :email],
+            update_only: [:commits]
+          )
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/repository.rb b/app/models/repository.rb
index 520c2b455e80fb..8dcf66bde320aa 100644
--- a/app/models/repository.rb
+++ b/app/models/repository.rb
@@ -379,6 +379,24 @@ def languages
     raw_repository.languages(root_ref)
   end
 
+  # Returns all unique contributors to the repository using git shortlog.
+  # More efficient than the `contributors` method for large repositories.
+  #
+  # @param ref [String] optional ref to limit contributors to (defaults to all refs)
+  # @param order [Symbol] sort order - :commits (default), :name, or :email
+  # @param contributor_type [Symbol] :author (default) or :committer
+  # @return [Array<Hash>] array of contributor hashes with :name, :email, :commits keys
+  def all_contributors(ref: nil, order: :commits, contributor_type: :author)
+    return [] if empty?
+
+    revisions = ref.present? ? [ref] : []
+    raw_repository.list_contributors(
+      revisions: revisions,
+      order: order,
+      contributor_type: contributor_type
+    )
+  end
+
   def keep_around(*shas, source:)
     Gitlab::Git::KeepAround.execute(self, shas, source: source)
   end
diff --git a/app/services/git/branch_hooks_service.rb b/app/services/git/branch_hooks_service.rb
index cd1abbdab4b576..37f8ad3d8a756b 100644
--- a/app/services/git/branch_hooks_service.rb
+++ b/app/services/git/branch_hooks_service.rb
@@ -99,6 +99,7 @@ def branch_change_hooks
       enqueue_process_commit_messages
       enqueue_jira_connect_sync_messages
       track_ci_config_change_event
+      enqueue_contributors_cache_refresh
     end
 
     def branch_remove_hooks
@@ -184,6 +185,10 @@ def enqueue_jira_connect_remove_branches
       )
     end
 
+    def enqueue_contributors_cache_refresh
+      Projects::ContributorsCacheWorker.perform_async(project.id, branch_name)
+    end
+
     def filtered_commit_shas
       limited_commits.select { |commit| Atlassian::JiraIssueKeyExtractor.has_keys?(commit.safe_message) }.map(&:sha)
     end
diff --git a/app/views/projects/_contributors_panel.html.haml b/app/views/projects/_contributors_panel.html.haml
new file mode 100644
index 00000000000000..f8da113aa5c67b
--- /dev/null
+++ b/app/views/projects/_contributors_panel.html.haml
@@ -0,0 +1,67 @@
+-# Contributors panel showing top contributors with avatars
+-# Links to the full contributor analytics page at group/project/-/graphs/(branch)
+
+- return unless can?(current_user, :read_code, project)
+- return if project.empty_repo?
+
+- all_contributors = project_contributors(project)
+- return if all_contributors.empty?
+
+- total_count = all_contributors.size
+- display_contributors = all_contributors.first(12)
+- remaining_count = [total_count - display_contributors.size, 0].max
+- emails = display_contributors.map { |c| c[:email].to_s.downcase }.uniq
+- users_by_email = {}
+- User.by_any_email(emails).includes(:emails).each do |user|
+  - users_by_email[user.email.downcase] = user
+  - user.emails.each { |email_record| users_by_email[email_record.email.downcase] ||= user }
+
+.project-page-sidebar-block.gl-py-4.gl-border-b.gl-border-b-subtle{ data: { testid: 'contributors-panel' } }
+  .gl-flex.gl-justify-between.gl-items-center.gl-mb-3
+    %h3.gl-text-sm.gl-font-bold.gl-m-0
+      = s_('ProjectPage|Contributors')
+      - if total_count > 0
+        %span.gl-text-secondary.gl-font-normal.gl-ml-1= total_count
+    = link_to project_graph_path(project, project.default_branch || 'HEAD'),
+        class: 'gl-text-sm gl-text-link',
+        data: { testid: 'view-all-contributors-link' } do
+      = s_('ProjectPage|View all')
+
+  .contributors-avatars.gl-flex.gl-flex-wrap.gl-gap-2
+    - display_contributors.each_with_index do |contributor, index|
+      - user = users_by_email[contributor[:email].to_s.downcase]
+      - commit_text = n_('%d commit', '%d commits', contributor[:commits]) % contributor[:commits]
+      - is_last = (index == display_contributors.size - 1) && remaining_count > 0
+      - if user
+        - if is_last
+          -# Last avatar with remaining count pill overlay
+          - display_remaining = remaining_count >= 1000 ? "#{(remaining_count / 100).floor / 10.0}k".sub('.0k', 'k') : remaining_count.to_s
+          - display_text = "+#{display_remaining}"
+          = link_to project_graph_path(project, project.default_branch || 'HEAD'),
+              class: 'gl-relative gl-inline-block has-tooltip',
+              title: n_('and %d more contributor', 'and %d more contributors', remaining_count) % remaining_count,
+              data: { container: 'body' } do
+            = user_avatar_without_link(user: user, size: 32, has_tooltip: false)
+            %span.gl-absolute.gl-px-1.gl-rounded-pill.gl-text-xs.gl-font-bold.gl-no-underline.gl-bg-subtle.gl-text-default.gl-border.gl-border-default{ style: 'bottom: -4px; right: -6px; padding-top: 1px; padding-bottom: 1px;' }
+              = display_text
+        - else
+          = link_to user_path(user),
+              class: 'js-user-link gl-inline-block',
+              data: { user_id: user.id, username: user.username, name: user.name, avatar_url: user.avatar_url, commit_count_text: commit_text } do
+            = user_avatar_without_link(user: user, size: 32, has_tooltip: false)
+      - else
+        -# Non-registered users: show email tooltip above avatar
+        - if is_last
+          - display_remaining = remaining_count >= 1000 ? "#{(remaining_count / 100).floor / 10.0}k".sub('.0k', 'k') : remaining_count.to_s
+          - display_text = "+#{display_remaining}"
+          = link_to project_graph_path(project, project.default_branch || 'HEAD'),
+              class: 'gl-relative gl-inline-block has-tooltip',
+              title: n_('and %d more contributor', 'and %d more contributors', remaining_count) % remaining_count,
+              data: { container: 'body' } do
+            = user_avatar_without_link(user_email: contributor[:email], size: 32, has_tooltip: false)
+            %span.gl-absolute.gl-px-1.gl-rounded-pill.gl-text-xs.gl-font-bold.gl-no-underline.gl-bg-subtle.gl-text-default.gl-border.gl-border-default{ style: 'bottom: -4px; right: -6px; padding-top: 1px; padding-bottom: 1px;' }
+              = display_text
+        - else
+          %span.has-tooltip{ title: "#{contributor[:email]} - #{commit_text}",
+              data: { container: 'body', placement: 'top' } }
+            = user_avatar_without_link(user_email: contributor[:email], size: 32, has_tooltip: false)
diff --git a/app/views/projects/_sidebar.html.haml b/app/views/projects/_sidebar.html.haml
index c069bcc03043db..5423e0e93ca6c9 100644
--- a/app/views/projects/_sidebar.html.haml
+++ b/app/views/projects/_sidebar.html.haml
@@ -41,6 +41,9 @@
               'aria-hidden': true,
               alt: 'Project badge' }>
 
+  -# Contributors panel
+  = render 'projects/contributors_panel', project: @project
+
   -# Invite members
   - if @project.empty_repo? && can?(current_user, :invite_member, @project)
     .project-page-sidebar-block.gl-py-4.gl-border-b.gl-border-b-subtle
diff --git a/app/workers/all_queues.yml b/app/workers/all_queues.yml
index a4c6b8436244e3..e55c9afa2dc2a4 100644
--- a/app/workers/all_queues.yml
+++ b/app/workers/all_queues.yml
@@ -4767,6 +4767,16 @@
   :idempotent: true
   :tags: []
   :queue_namespace:
+- :name: projects_contributors_cache
+  :worker_name: Projects::ContributorsCacheWorker
+  :feature_category: :source_code_management
+  :has_external_dependencies: false
+  :urgency: :low
+  :resource_boundary: :cpu
+  :weight: 1
+  :idempotent: true
+  :tags: []
+  :queue_namespace:
 - :name: projects_delete_branch
   :worker_name: Projects::DeleteBranchWorker
   :feature_category: :source_code_management
diff --git a/app/workers/projects/contributors_cache_worker.rb b/app/workers/projects/contributors_cache_worker.rb
new file mode 100644
index 00000000000000..485dc3b2d0ded1
--- /dev/null
+++ b/app/workers/projects/contributors_cache_worker.rb
@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Projects
+  # Worker to refresh contributor statistics for a project branch.
+  # Triggered on push events via BranchHooksService.
+  #
+  # Deduplication strategy:
+  # - Uses :until_executed to prevent duplicate jobs while one is running
+  # - TTL of 1 minute ensures rapid updates while preventing excessive refreshes
+  # - if_deduplicated: :reschedule_once ensures we don't miss updates that arrive
+  #   while the job is executing
+  class ContributorsCacheWorker
+    include ApplicationWorker
+
+    idempotent!
+    deduplicate :until_executed, if_deduplicated: :reschedule_once, ttl: 1.minute
+    defer_on_database_health_signal :gitlab_main, [:project_contributors], 1.minute
+
+    data_consistency :delayed
+
+    sidekiq_options retry: 3
+
+    feature_category :source_code_management
+    urgency :low
+    worker_resource_boundary :cpu
+
+    # @param project_id [Integer] the project to refresh contributors for
+    # @param branch [String, nil] specific branch to refresh, or nil for all-branches aggregate
+    def perform(project_id, branch = nil)
+      project = Project.find_by_id(project_id)
+      return unless project
+
+      Projects::Contributor.refresh_from_repository(project, branch: branch)
+    end
+  end
+end
diff --git a/db/docs/project_contributors.yml b/db/docs/project_contributors.yml
new file mode 100644
index 00000000000000..b77008ace0868b
--- /dev/null
+++ b/db/docs/project_contributors.yml
@@ -0,0 +1,13 @@
+---
+table_name: project_contributors
+classes:
+- ProjectContributor
+feature_categories:
+- source_code_management
+description: Stores contributor statistics (commit counts) per project and displays them in the project contributors panel.
+introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/XXXXX
+milestone: '18.7'
+gitlab_schema: gitlab_main_org
+sharding_key:
+  project_id: projects
+table_size: small
diff --git a/db/migrate/20251129180216_create_project_contributors.rb b/db/migrate/20251129180216_create_project_contributors.rb
new file mode 100644
index 00000000000000..5819dcc84a54ff
--- /dev/null
+++ b/db/migrate/20251129180216_create_project_contributors.rb
@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class CreateProjectContributors < Gitlab::Database::Migration[2.3]
+  milestone '18.7'
+
+  def change
+    create_table :project_contributors do |t|
+      t.bigint :project_id, null: false
+      t.text :branch, null: false, limit: 1024
+      t.text :email, null: false, limit: 1024
+      t.integer :commits, null: false, default: 0
+      t.timestamps_with_timezone null: false
+
+      # Primary lookup: get top contributors for a project+branch sorted by commits desc
+      # This is the most common query pattern for the contributors panel
+      t.index [:project_id, :branch, :commits],
+        order: { commits: :desc },
+        name: 'index_project_contributors_on_project_branch_commits'
+
+      # Uniqueness constraint: one entry per project+branch+email combination
+      # Email is the canonical identifier for a contributor
+      t.index [:project_id, :branch, :email],
+        unique: true,
+        name: 'index_project_contributors_unique'
+    end
+  end
+end
diff --git a/db/migrate/20251129180217_add_project_contributors_project_fk.rb b/db/migrate/20251129180217_add_project_contributors_project_fk.rb
new file mode 100644
index 00000000000000..250b8eb020df77
--- /dev/null
+++ b/db/migrate/20251129180217_add_project_contributors_project_fk.rb
@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class AddProjectContributorsProjectFk < Gitlab::Database::Migration[2.3]
+  milestone '18.7'
+
+  disable_ddl_transaction!
+
+  def up
+    add_concurrent_foreign_key :project_contributors, :projects, column: :project_id, on_delete: :cascade
+  end
+
+  def down
+    with_lock_retries do
+      remove_foreign_key :project_contributors, column: :project_id
+    end
+  end
+end
diff --git a/db/schema_migrations/20251129180216 b/db/schema_migrations/20251129180216
new file mode 100644
index 00000000000000..1bf7e60327163f
--- /dev/null
+++ b/db/schema_migrations/20251129180216
@@ -0,0 +1 @@
+dedd7e397263450e68221dad65323e9cd1776695b34ddbff7ae6dde78cf41a84
\ No newline at end of file
diff --git a/db/schema_migrations/20251129180217 b/db/schema_migrations/20251129180217
new file mode 100644
index 00000000000000..19c03b79113033
--- /dev/null
+++ b/db/schema_migrations/20251129180217
@@ -0,0 +1 @@
+0920a9ea8d4a22ec5fee5f5c01f6d5c21136baa7c2706f61061587f6f5f52c08
\ No newline at end of file
diff --git a/db/structure.sql b/db/structure.sql
index ac2a0400db502d..04f694a881c8f9 100644
--- a/db/structure.sql
+++ b/db/structure.sql
@@ -892,6 +892,32 @@ BEGIN
 END
 $$;
 
+CREATE FUNCTION siphon_alter_publication(pbl text, tbl text, op integer) RETURNS void
+    LANGUAGE plpgsql SECURITY DEFINER
+    AS $_$
+DECLARE
+  operation TEXT;
+BEGIN
+  IF pbl !~ '^[a-zA-Z_][a-zA-Z0-9_]*$' THEN
+    RAISE EXCEPTION 'Invalid publication name';
+  END IF;
+
+  IF tbl !~ '^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$' THEN
+    RAISE EXCEPTION 'Invalid table name format: must be schema-qualified (e.g., users)';
+  END IF;
+
+  IF op = 0 THEN
+    operation := 'ADD';
+  ELSIF op = 1 THEN
+    operation := 'DROP';
+  ELSE
+    RAISE EXCEPTION 'Invalid operation parameter: op must be 0 (DROP) or 1 (ADD)';
+  END IF;
+  
+  EXECUTE pg_catalog.format('ALTER PUBLICATION %s %s TABLE %s', pbl, operation, tbl);
+END;
+$_$;
+
 CREATE FUNCTION sync_issues_dates_with_work_item_dates_sources() RETURNS trigger
     LANGUAGE plpgsql
     AS $$
@@ -5230,6 +5256,36 @@ RETURN NULL;
 END
 $$;
 
+CREATE TABLE ai_code_suggestion_events (
+    id bigint NOT NULL,
+    "timestamp" timestamp with time zone NOT NULL,
+    user_id bigint NOT NULL,
+    organization_id bigint NOT NULL,
+    created_at timestamp with time zone NOT NULL,
+    updated_at timestamp with time zone NOT NULL,
+    event smallint NOT NULL,
+    namespace_path text,
+    payload jsonb,
+    CONSTRAINT check_ba9ae3f258 CHECK ((char_length(namespace_path) <= 255))
+)
+PARTITION BY RANGE ("timestamp");
+
+CREATE TABLE ai_duo_chat_events (
+    id bigint NOT NULL,
+    "timestamp" timestamp with time zone NOT NULL,
+    user_id bigint NOT NULL,
+    personal_namespace_id bigint,
+    created_at timestamp with time zone NOT NULL,
+    updated_at timestamp with time zone NOT NULL,
+    event smallint NOT NULL,
+    namespace_path text,
+    payload jsonb,
+    organization_id bigint,
+    CONSTRAINT check_628cdfbf3f CHECK ((char_length(namespace_path) <= 255)),
+    CONSTRAINT check_f759f45177 CHECK ((organization_id IS NOT NULL))
+)
+PARTITION BY RANGE ("timestamp");
+
 CREATE TABLE ai_events_counts (
     id bigint NOT NULL,
     events_date date NOT NULL,
@@ -5241,6 +5297,21 @@ CREATE TABLE ai_events_counts (
 )
 PARTITION BY RANGE (events_date);
 
+CREATE TABLE ai_troubleshoot_job_events (
+    id bigint NOT NULL,
+    "timestamp" timestamp with time zone NOT NULL,
+    user_id bigint NOT NULL,
+    job_id bigint NOT NULL,
+    project_id bigint NOT NULL,
+    created_at timestamp with time zone NOT NULL,
+    updated_at timestamp with time zone NOT NULL,
+    event smallint NOT NULL,
+    namespace_path text,
+    payload jsonb,
+    CONSTRAINT check_29d6dbc329 CHECK ((char_length(namespace_path) <= 255))
+)
+PARTITION BY RANGE ("timestamp");
+
 CREATE TABLE ai_usage_events (
     id bigint NOT NULL,
     "timestamp" timestamp with time zone NOT NULL,
@@ -5972,7 +6043,7 @@ PARTITION BY RANGE (created_at);
 
 CREATE TABLE loose_foreign_keys_deleted_records (
     id bigint NOT NULL,
-    partition bigint DEFAULT 1 NOT NULL,
+    partition bigint DEFAULT 9 NOT NULL,
     primary_key_value bigint NOT NULL,
     status smallint DEFAULT 1 NOT NULL,
     created_at timestamp with time zone DEFAULT now() NOT NULL,
@@ -6158,7 +6229,7 @@ PARTITION BY RANGE (namespace_id);
 
 CREATE TABLE p_knowledge_graph_tasks (
     id bigint NOT NULL,
-    partition_id bigint DEFAULT 1 NOT NULL,
+    partition_id bigint DEFAULT 13 NOT NULL,
     zoekt_node_id bigint NOT NULL,
     namespace_id bigint NOT NULL,
     knowledge_graph_replica_id bigint NOT NULL,
@@ -6168,6 +6239,7 @@ CREATE TABLE p_knowledge_graph_tasks (
     state smallint DEFAULT 0 NOT NULL,
     task_type smallint NOT NULL,
     retries_left smallint NOT NULL,
+    metadata jsonb DEFAULT '"{}"'::jsonb NOT NULL,
     CONSTRAINT c_p_knowledge_graph_tasks_on_retries_left CHECK (((retries_left > 0) OR ((retries_left = 0) AND (state = 255))))
 )
 PARTITION BY LIST (partition_id);
@@ -6187,7 +6259,7 @@ CREATE TABLE p_sent_notifications (
     issue_email_participant_id bigint,
     namespace_id bigint NOT NULL,
     created_at timestamp with time zone NOT NULL,
-    partition integer DEFAULT 1 NOT NULL,
+    partition integer DEFAULT 2 NOT NULL,
     noteable_type text,
     commit_id text,
     reply_key text NOT NULL,
@@ -6357,7 +6429,7 @@ PARTITION BY RANGE (created_at);
 
 CREATE TABLE zoekt_tasks (
     id bigint NOT NULL,
-    partition_id bigint DEFAULT 1 NOT NULL,
+    partition_id bigint DEFAULT 19 NOT NULL,
     zoekt_node_id bigint NOT NULL,
     zoekt_repository_id bigint NOT NULL,
     project_identifier bigint NOT NULL,
@@ -11076,20 +11148,6 @@ CREATE SEQUENCE ai_catalog_items_id_seq
 
 ALTER SEQUENCE ai_catalog_items_id_seq OWNED BY ai_catalog_items.id;
 
-CREATE TABLE ai_code_suggestion_events (
-    id bigint NOT NULL,
-    "timestamp" timestamp with time zone NOT NULL,
-    user_id bigint NOT NULL,
-    organization_id bigint NOT NULL,
-    created_at timestamp with time zone NOT NULL,
-    updated_at timestamp with time zone NOT NULL,
-    event smallint NOT NULL,
-    namespace_path text,
-    payload jsonb,
-    CONSTRAINT check_ba9ae3f258 CHECK ((char_length(namespace_path) <= 255))
-)
-PARTITION BY RANGE ("timestamp");
-
 CREATE SEQUENCE ai_code_suggestion_events_id_seq
     START WITH 1
     INCREMENT BY 1
@@ -11148,22 +11206,6 @@ CREATE SEQUENCE ai_conversation_threads_id_seq
 
 ALTER SEQUENCE ai_conversation_threads_id_seq OWNED BY ai_conversation_threads.id;
 
-CREATE TABLE ai_duo_chat_events (
-    id bigint NOT NULL,
-    "timestamp" timestamp with time zone NOT NULL,
-    user_id bigint NOT NULL,
-    personal_namespace_id bigint,
-    created_at timestamp with time zone NOT NULL,
-    updated_at timestamp with time zone NOT NULL,
-    event smallint NOT NULL,
-    namespace_path text,
-    payload jsonb,
-    organization_id bigint,
-    CONSTRAINT check_628cdfbf3f CHECK ((char_length(namespace_path) <= 255)),
-    CONSTRAINT check_f759f45177 CHECK ((organization_id IS NOT NULL))
-)
-PARTITION BY RANGE ("timestamp");
-
 CREATE SEQUENCE ai_duo_chat_events_id_seq
     START WITH 1
     INCREMENT BY 1
@@ -11284,8 +11326,8 @@ CREATE TABLE ai_settings (
     duo_core_features_enabled boolean,
     duo_agent_platform_service_url text,
     duo_agent_platform_request_count integer DEFAULT 0 NOT NULL,
-    foundational_agents_default_enabled boolean DEFAULT true,
     ai_gateway_timeout_seconds integer DEFAULT 60,
+    foundational_agents_default_enabled boolean DEFAULT true,
     minimum_access_level_execute smallint,
     minimum_access_level_manage smallint,
     minimum_access_level_enable_on_projects smallint,
@@ -11313,21 +11355,6 @@ CREATE TABLE ai_testing_terms_acceptances (
     CONSTRAINT check_5efe98894e CHECK ((char_length(user_email) <= 255))
 );
 
-CREATE TABLE ai_troubleshoot_job_events (
-    id bigint NOT NULL,
-    "timestamp" timestamp with time zone NOT NULL,
-    user_id bigint NOT NULL,
-    job_id bigint NOT NULL,
-    project_id bigint NOT NULL,
-    created_at timestamp with time zone NOT NULL,
-    updated_at timestamp with time zone NOT NULL,
-    event smallint NOT NULL,
-    namespace_path text,
-    payload jsonb,
-    CONSTRAINT check_29d6dbc329 CHECK ((char_length(namespace_path) <= 255))
-)
-PARTITION BY RANGE ("timestamp");
-
 CREATE SEQUENCE ai_troubleshoot_job_events_id_seq
     START WITH 1
     INCREMENT BY 1
@@ -24639,6 +24666,27 @@ CREATE SEQUENCE project_compliance_violations_issues_id_seq
 
 ALTER SEQUENCE project_compliance_violations_issues_id_seq OWNED BY project_compliance_violations_issues.id;
 
+CREATE TABLE project_contributors (
+    id bigint NOT NULL,
+    project_id bigint NOT NULL,
+    branch text NOT NULL,
+    email text NOT NULL,
+    commits integer DEFAULT 0 NOT NULL,
+    created_at timestamp with time zone NOT NULL,
+    updated_at timestamp with time zone NOT NULL,
+    CONSTRAINT check_4b1f24a452 CHECK ((char_length(branch) <= 1024)),
+    CONSTRAINT check_791d0f0c17 CHECK ((char_length(email) <= 1024))
+);
+
+CREATE SEQUENCE project_contributors_id_seq
+    START WITH 1
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1;
+
+ALTER SEQUENCE project_contributors_id_seq OWNED BY project_contributors.id;
+
 CREATE TABLE project_control_compliance_statuses (
     id bigint NOT NULL,
     created_at timestamp with time zone NOT NULL,
@@ -26904,8 +26952,8 @@ CREATE TABLE security_policy_dismissals (
     dismissal_types smallint[] DEFAULT '{}'::smallint[] NOT NULL,
     comment text,
     status smallint DEFAULT 0 NOT NULL,
-    licenses jsonb DEFAULT '{}'::jsonb NOT NULL,
     license_occurrence_uuids text[] DEFAULT '{}'::text[] NOT NULL,
+    licenses jsonb DEFAULT '{}'::jsonb NOT NULL,
     CONSTRAINT check_654ff06528 CHECK ((char_length(comment) <= 255)),
     CONSTRAINT check_88beed9dc9 CHECK ((security_findings_uuids IS NOT NULL))
 );
@@ -28717,8 +28765,8 @@ CREATE TABLE user_preferences (
     work_items_display_settings jsonb DEFAULT '{}'::jsonb NOT NULL,
     default_duo_add_on_assignment_id bigint,
     markdown_maintain_indentation boolean DEFAULT false NOT NULL,
-    project_studio_enabled boolean DEFAULT false NOT NULL,
     merge_request_dashboard_show_drafts boolean DEFAULT true NOT NULL,
+    project_studio_enabled boolean DEFAULT false NOT NULL,
     duo_default_namespace_id bigint,
     policy_advanced_editor boolean DEFAULT false NOT NULL,
     early_access_studio_participant boolean DEFAULT false NOT NULL,
@@ -29697,8 +29745,8 @@ CREATE TABLE vulnerability_occurrences (
     initial_pipeline_id bigint,
     latest_pipeline_id bigint,
     security_project_tracked_context_id bigint,
-    detected_at timestamp with time zone DEFAULT now(),
     new_uuid uuid,
+    detected_at timestamp with time zone DEFAULT now(),
     CONSTRAINT check_4a3a60f2ba CHECK ((char_length(solution) <= 7000)),
     CONSTRAINT check_ade261da6b CHECK ((char_length(description) <= 15000)),
     CONSTRAINT check_f602da68dd CHECK ((char_length(cve) <= 48400))
@@ -32703,6 +32751,8 @@ ALTER TABLE ONLY project_compliance_violations ALTER COLUMN id SET DEFAULT nextv
 
 ALTER TABLE ONLY project_compliance_violations_issues ALTER COLUMN id SET DEFAULT nextval('project_compliance_violations_issues_id_seq'::regclass);
 
+ALTER TABLE ONLY project_contributors ALTER COLUMN id SET DEFAULT nextval('project_contributors_id_seq'::regclass);
+
 ALTER TABLE ONLY project_control_compliance_statuses ALTER COLUMN id SET DEFAULT nextval('project_control_compliance_statuses_id_seq'::regclass);
 
 ALTER TABLE ONLY project_custom_attributes ALTER COLUMN id SET DEFAULT nextval('project_custom_attributes_id_seq'::regclass);
@@ -36317,6 +36367,9 @@ ALTER TABLE ONLY project_compliance_violations_issues
 ALTER TABLE ONLY project_compliance_violations
     ADD CONSTRAINT project_compliance_violations_pkey PRIMARY KEY (id);
 
+ALTER TABLE ONLY project_contributors
+    ADD CONSTRAINT project_contributors_pkey PRIMARY KEY (id);
+
 ALTER TABLE ONLY project_control_compliance_statuses
     ADD CONSTRAINT project_control_compliance_statuses_pkey PRIMARY KEY (id);
 
@@ -43342,6 +43395,10 @@ CREATE INDEX index_project_compliance_violations_issues_on_issue_id ON project_c
 
 CREATE INDEX index_project_compliance_violations_issues_on_project_id ON project_compliance_violations_issues USING btree (project_id);
 
+CREATE INDEX index_project_contributors_on_project_branch_commits ON project_contributors USING btree (project_id, branch, commits DESC);
+
+CREATE UNIQUE INDEX index_project_contributors_unique ON project_contributors USING btree (project_id, branch, email);
+
 CREATE INDEX index_project_custom_attributes_on_key_and_value ON project_custom_attributes USING btree (key, value);
 
 CREATE UNIQUE INDEX index_project_custom_attributes_on_project_id_and_key ON project_custom_attributes USING btree (project_id, key);
@@ -54207,3 +54264,61 @@ ALTER TABLE ONLY user_follow_users
 
 ALTER TABLE ONLY user_follow_users
     ADD CONSTRAINT user_follow_users_follower_id_fkey FOREIGN KEY (follower_id) REFERENCES users(id) ON DELETE CASCADE;
+
+CREATE PUBLICATION siphon_publication_main_1 WITH (publish = 'insert, update, delete, truncate');
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY epic_issues;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY epic_user_mentions;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY epics;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY events;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY issue_assignees;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY issue_links;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY issues;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY members;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY merge_request_assignees;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY merge_request_reviewers;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY merge_requests;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY merge_requests_closing_issues;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY namespaces;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY notes;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY project_repositories;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY projects;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY push_event_payloads;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY related_epic_links;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY routes;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY shards;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY users;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY vulnerabilities;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY vulnerability_feedback;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY vulnerability_identifiers;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY vulnerability_issue_links;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY vulnerability_merge_request_links;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY vulnerability_occurrences;
+
+ALTER PUBLICATION siphon_publication_main_1 ADD TABLE ONLY vulnerability_scanners;
diff --git a/lib/gitlab/git/repository.rb b/lib/gitlab/git/repository.rb
index 7df6a542fd6be0..282e05232a469c 100644
--- a/lib/gitlab/git/repository.rb
+++ b/lib/gitlab/git/repository.rb
@@ -846,6 +846,22 @@ def languages(ref = nil)
         end
       end
 
+      # Returns all unique contributors to the repository.
+      #
+      # @param revisions [Array<String>] optional list of revisions to consider
+      # @param order [Symbol] sort order - :commits (default), :name, or :email
+      # @param contributor_type [Symbol] :author (default) or :committer
+      # @return [Array<Hash>] array of contributor hashes with :name, :email, :commits keys
+      def list_contributors(revisions: [], order: :commits, contributor_type: :author)
+        wrapped_gitaly_errors do
+          gitaly_commit_client.list_contributors(
+            revisions: revisions,
+            order: order,
+            contributor_type: contributor_type
+          )
+        end
+      end
+
       def license
         wrapped_gitaly_errors do
           response = gitaly_repository_client.find_license
diff --git a/lib/gitlab/gitaly_client/commit_service.rb b/lib/gitlab/gitaly_client/commit_service.rb
index cdfa344417bb63..07b14bf4f0451f 100644
--- a/lib/gitlab/gitaly_client/commit_service.rb
+++ b/lib/gitlab/gitaly_client/commit_service.rb
@@ -617,8 +617,70 @@ def get_patch_id(old_revision, new_revision)
         response.patch_id
       end
 
+      # Lists all unique contributors to the repository.
+      #
+      # In Git, there's a distinction between author and committer:
+      # - Author: The person who originally wrote the code
+      # - Committer: The person who last applied the commit (e.g., during rebase/cherry-pick)
+      #
+      # For contributor statistics we want to show authors, as they represent who wrote the code.
+      #
+      # @param revisions [Array<String>] optional list of revisions to consider. If empty, all refs are considered.
+      # @param order [Symbol] sort order - :commits (default), :name, or :email
+      # @param contributor_type [Symbol] :author (default) or :committer
+      # @return [Array<Hash>] array of contributor hashes with :email, :commits keys
+      def list_contributors(revisions: [], order: :commits, contributor_type: :author)
+        request = Gitaly::ListContributorsRequest.new(
+          repository: @gitaly_repo,
+          revisions: Array.wrap(revisions),
+          order: map_contributor_sort_order(order),
+          contributor_type: map_contributor_type(contributor_type)
+        )
+
+        response = gitaly_client_call(
+          @repository.storage,
+          :commit_service,
+          :list_contributors,
+          request,
+          timeout: GitalyClient.long_timeout
+        )
+
+        contributors = []
+        response.each do |message|
+          message.contributors.each do |contributor|
+            contributors << {
+              name: EncodingHelper.encode!(contributor.name.dup),
+              email: EncodingHelper.encode!(contributor.email.dup),
+              commits: contributor.commits
+            }
+          end
+        end
+
+        contributors
+      end
+
       private
 
+      def map_contributor_sort_order(order)
+        case order
+        when :name
+          Gitaly::ListContributorsRequest::SortBy::NAME
+        when :email
+          Gitaly::ListContributorsRequest::SortBy::EMAIL
+        else
+          Gitaly::ListContributorsRequest::SortBy::COMMITS
+        end
+      end
+
+      def map_contributor_type(contributor_type)
+        case contributor_type
+        when :committer
+          Gitaly::ListContributorsRequest::ContributorType::COMMITTER
+        else
+          Gitaly::ListContributorsRequest::ContributorType::AUTHOR
+        end
+      end
+
       def parse_global_options!(options)
         literal_pathspec = options.delete(:literal_pathspec)
         Gitaly::GlobalOptions.new(literal_pathspecs: literal_pathspec)
diff --git a/locale/gitlab.pot b/locale/gitlab.pot
index 92562f780fdb2c..5a438a83341479 100644
--- a/locale/gitlab.pot
+++ b/locale/gitlab.pot
@@ -52249,6 +52249,9 @@ msgstr ""
 msgid "ProjectOverview|You must sign in to star a project"
 msgstr ""
 
+msgid "ProjectPage|Contributors"
+msgstr ""
+
 msgid "ProjectPage|Copy project ID: %{id}"
 msgstr ""
 
@@ -52273,6 +52276,9 @@ msgstr ""
 msgid "ProjectPage|Unable to load default branch"
 msgstr ""
 
+msgid "ProjectPage|View all"
+msgstr ""
+
 msgid "ProjectQualitySummary|An error occurred while trying to fetch project quality statistics"
 msgstr ""
 
@@ -79204,6 +79210,11 @@ msgstr ""
 msgid "and"
 msgstr ""
 
+msgid "and %d more contributor"
+msgid_plural "and %d more contributors"
+msgstr[0] ""
+msgstr[1] ""
+
 msgid "and regex description must be either both set, or neither."
 msgstr ""
 
diff --git a/spec/factories/project_contributors.rb b/spec/factories/project_contributors.rb
new file mode 100644
index 00000000000000..16d6f0d5d9db0e
--- /dev/null
+++ b/spec/factories/project_contributors.rb
@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :project_contributor, class: 'Projects::Contributor' do
+    project
+    branch { 'main' }
+    sequence(:email) { |n| "contributor#{n}@example.com" }
+    commits { 10 }
+  end
+end
diff --git a/spec/lib/gitlab/gitaly_client/commit_service_spec.rb b/spec/lib/gitlab/gitaly_client/commit_service_spec.rb
index 32c9bab5b1cfc4..f89e75e0462ed0 100644
--- a/spec/lib/gitlab/gitaly_client/commit_service_spec.rb
+++ b/spec/lib/gitlab/gitaly_client/commit_service_spec.rb
@@ -1454,4 +1454,78 @@ def wrap_commits(commits)
       end
     end
   end
+
+  describe '#list_contributors' do
+    it 'returns contributors sorted by commit count by default' do
+      contributors = client.list_contributors
+
+      expect(contributors).to be_an(Array)
+      expect(contributors).not_to be_empty
+      expect(contributors.first).to include(:name, :email, :commits)
+      expect(contributors.first[:commits]).to be_a(Integer)
+
+      # Verify sorted by commits descending
+      commits = contributors.pluck(:commits)
+      expect(commits).to eq(commits.sort.reverse)
+    end
+
+    it 'sends correct request with default parameters' do
+      expect_any_instance_of(Gitaly::CommitService::Stub).to receive(:list_contributors)
+        .with(
+          having_attributes(
+            revisions: [],
+            order: :COMMITS,
+            contributor_type: :AUTHOR
+          ),
+          kind_of(Hash)
+        )
+        .and_call_original
+
+      client.list_contributors
+    end
+
+    context 'with order parameter' do
+      it 'maps :commits to COMMITS' do
+        expect_any_instance_of(Gitaly::CommitService::Stub).to receive(:list_contributors)
+          .with(having_attributes(order: :COMMITS), kind_of(Hash))
+          .and_call_original
+
+        client.list_contributors(order: :commits)
+      end
+
+      it 'maps :name to NAME' do
+        expect_any_instance_of(Gitaly::CommitService::Stub).to receive(:list_contributors)
+          .with(having_attributes(order: :NAME), kind_of(Hash))
+          .and_call_original
+
+        client.list_contributors(order: :name)
+      end
+
+      it 'maps :email to EMAIL' do
+        expect_any_instance_of(Gitaly::CommitService::Stub).to receive(:list_contributors)
+          .with(having_attributes(order: :EMAIL), kind_of(Hash))
+          .and_call_original
+
+        client.list_contributors(order: :email)
+      end
+    end
+
+    context 'with contributor_type parameter' do
+      it 'maps :author to AUTHOR' do
+        expect_any_instance_of(Gitaly::CommitService::Stub).to receive(:list_contributors)
+          .with(having_attributes(contributor_type: :AUTHOR), kind_of(Hash))
+          .and_call_original
+
+        client.list_contributors(contributor_type: :author)
+      end
+
+      it 'maps :committer to COMMITTER' do
+        expect_any_instance_of(Gitaly::CommitService::Stub).to receive(:list_contributors)
+          .with(having_attributes(contributor_type: :COMMITTER), kind_of(Hash))
+          .and_call_original
+
+        client.list_contributors(contributor_type: :committer)
+      end
+    end
+  end
 end
diff --git a/spec/models/projects/contributor_spec.rb b/spec/models/projects/contributor_spec.rb
new file mode 100644
index 00000000000000..ea1818507fc95c
--- /dev/null
+++ b/spec/models/projects/contributor_spec.rb
@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Projects::Contributor, feature_category: :source_code_management do
+  describe 'associations' do
+    it { is_expected.to belong_to(:project) }
+  end
+
+  describe 'validations' do
+    subject { build(:project_contributor) }
+
+    it { is_expected.to validate_presence_of(:project) }
+    it { is_expected.to validate_presence_of(:branch) }
+    it { is_expected.to validate_presence_of(:email) }
+    it { is_expected.to validate_presence_of(:commits) }
+    it { is_expected.to validate_length_of(:branch).is_at_most(1024) }
+    it { is_expected.to validate_length_of(:email).is_at_most(1024) }
+    it { is_expected.to validate_numericality_of(:commits).only_integer.is_greater_than_or_equal_to(0) }
+
+    it 'validates uniqueness of email scoped to project and branch' do
+      is_expected.to validate_uniqueness_of(:email).scoped_to([:project_id,
+        :branch]).with_message('already exists for this project and branch')
+    end
+  end
+
+  describe 'scopes' do
+    let_it_be(:project) { create(:project) }
+    let_it_be(:contributor1) do
+      create(:project_contributor, project: project, branch: 'main', email: 'alice@example.com', commits: 100)
+    end
+
+    let_it_be(:contributor2) do
+      create(:project_contributor, project: project, branch: 'main', email: 'bob@example.com', commits: 50)
+    end
+
+    let_it_be(:contributor3) do
+      create(:project_contributor, project: project, branch: 'develop', email: 'charlie@example.com', commits: 75)
+    end
+
+    describe '.for_project' do
+      it 'returns contributors for the specified project' do
+        expect(described_class.for_project(project.id)).to contain_exactly(contributor1, contributor2, contributor3)
+      end
+    end
+
+    describe '.for_branch' do
+      it 'returns contributors for the specified branch' do
+        expect(described_class.for_branch('main')).to contain_exactly(contributor1, contributor2)
+      end
+    end
+
+    describe '.by_commits' do
+      it 'orders by commits descending' do
+        expect(described_class.for_branch('main').by_commits).to eq([contributor1, contributor2])
+      end
+    end
+
+    describe '.by_email' do
+      it 'orders by email ascending' do
+        expect(described_class.for_branch('main').by_email).to eq([contributor1, contributor2])
+      end
+    end
+  end
+
+  describe '.for_project_branch' do
+    let_it_be(:project) { create(:project) }
+    let_it_be(:contributor1) do
+      create(:project_contributor, project: project, branch: 'main', email: 'alice@example.com', commits: 100)
+    end
+
+    let_it_be(:contributor2) do
+      create(:project_contributor, project: project, branch: 'main', email: 'bob@example.com', commits: 50)
+    end
+
+    let_it_be(:contributor3) do
+      create(:project_contributor, project: project, branch: 'main', email: 'charlie@example.com', commits: 75)
+    end
+
+    it 'returns contributors for project and branch ordered by commits by default' do
+      result = described_class.for_project_branch(project.id, branch: 'main')
+      expect(result).to eq([contributor1, contributor3, contributor2])
+    end
+
+    it 'orders by email when specified' do
+      result = described_class.for_project_branch(project.id, branch: 'main', order: :email)
+      expect(result).to eq([contributor1, contributor2, contributor3])
+    end
+
+    it 'respects the limit parameter' do
+      result = described_class.for_project_branch(project.id, branch: 'main', limit: 2)
+      expect(result.count).to eq(2)
+    end
+  end
+end
-- 
GitLab