refactor(automerge): fix error handling, populate recent automerge tasks on restart (#39001)

* Refactor "automerge" related code, clarify many details (including "unique queue item", start check by pull head or commit)
* Fix automerge queue handler's error handling, clarify error messages
* Populate recent automerge tasks on restart to restore the previous aborted automerge tasks

Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

services/pull/check.go

@@ -297,7 +297,7 @@ func markPullRequestAsMergeable(ctx context.Context, pr *issues_model.PullReques
 	} else if !exist {
 		return
 	}
-	automergequeue.StartPRCheckAndAutoMerge(ctx, pr)
+	automergequeue.StartAutoMergeCheckByPullHead(ctx, pr)
 }
 
 // getMergeCommit checks if a pull request has been merged

services/pull/check_test.go

@@ -117,10 +117,9 @@ func TestMarkPullRequestAsMergeable(t *testing.T) {
 		prPatchCheckerQueue = nil
 	}()
 
-	addToQueueShaChan := make(chan string, 1)
-	defer test.MockVariableValue(&automergequeue.AddToQueue, func(pr *issues_model.PullRequest, sha string) {
-		addToQueueShaChan <- sha
-	})()
+	addToQueuePullChan := make(chan automergequeue.AutoMergeItem, 1)
+	defer test.MockVariableValue(&automergequeue.AddToQueue, func(item automergequeue.AutoMergeItem) { addToQueuePullChan <- item })()
+
 	ctx := t.Context()
 	_, _ = db.GetEngine(ctx).ID(2).Update(&issues_model.PullRequest{Status: issues_model.PullRequestStatusChecking})
 	pr := unittest.AssertExistsAndLoadBean(t, &issues_model.PullRequest{ID: 2})
@@ -140,8 +139,8 @@ func TestMarkPullRequestAsMergeable(t *testing.T) {
 	require.Equal(t, issues_model.PullRequestStatusMergeable, pr.Status)
 
 	select {
-	case sha := <-addToQueueShaChan:
-		assert.Equal(t, "985f0301dba5e7b34be866819cd15ad3d8f508ee", sha) // ref: refs/pull/3/head
+	case item := <-addToQueuePullChan:
+		assert.EqualValues(t, "pr:2:985f0301dba5e7b34be866819cd15ad3d8f508ee", item) // ref: refs/pull/3/head
 	case <-time.After(1 * time.Second):
 		assert.FailNow(t, "Timeout: nothing was added to automergequeue")
 	}

services/pull/ref.go

@@ -0,0 +1,55 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package pull
+
+import (
+	"context"
+	"errors"
+
+	issues_model "gitea.dev/models/issues"
+	repo_model "gitea.dev/models/repo"
+	"gitea.dev/modules/git"
+	"gitea.dev/modules/util"
+)
+
+func EnumPullRequestsByHeadCommitID(ctx context.Context, repo *repo_model.Repository, commitID string, filter func(*issues_model.PullRequest) bool) (pulls []*issues_model.PullRequest, _ error) {
+	gitRepo, err := git.OpenRepository(ctx, repo)
+	if err != nil {
+		return nil, err
+	}
+	defer gitRepo.Close()
+
+	refs, err := gitRepo.GetRefsBySha(ctx, commitID, git.PullPrefix)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, refStr := range refs {
+		ref := git.RefName(refStr)
+		prIndex, ok := ref.PullIndex()
+		if !ok {
+			continue
+		}
+
+		pull, err := issues_model.GetPullRequestByIndex(ctx, repo.ID, prIndex)
+		if err != nil {
+			if errors.Is(err, util.ErrNotExist) {
+				continue // ignore non-existing pull requests
+			}
+			return nil, err
+		}
+
+		if filter(pull) {
+			pulls = append(pulls, pull)
+		}
+	}
+	return pulls, nil
+}
+
+func GetMergeablePullRequestsByHeadCommitID(ctx context.Context, repo *repo_model.Repository, commitID string) ([]*issues_model.PullRequest, error) {
+	return EnumPullRequestsByHeadCommitID(ctx, repo, commitID, func(pr *issues_model.PullRequest) bool {
+		_ = pr.LoadIssue(ctx)
+		return pr.Issue != nil && !pr.Issue.IsClosed && !pr.HasMerged && pr.IsStatusMergeable()
+	})
+}

services/pull/ref_test.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package pull_test
+
+import (
+	"testing"
+
+	repo_model "gitea.dev/models/repo"
+	"gitea.dev/models/unittest"
+	"gitea.dev/services/pull"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestGetMergeablePullRequestsByHeadCommitID(t *testing.T) {
+	assert.NoError(t, unittest.PrepareTestDatabase())
+	repo1 := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 1})
+	pulls, err := pull.GetMergeablePullRequestsByHeadCommitID(t.Context(), repo1, "985f0301dba5e7b34be866819cd15ad3d8f508ee")
+	assert.NoError(t, err)
+	assert.Len(t, pulls, 1)
+}