feat(api): add last_sync to repository API (#37566)

This PR adds a new repository API field, `mirror_last_sync_at`, to
expose the timestamp of the last successful pull mirror sync.

Unlike `mirror_updated`, this field does not affect mirror scheduling
and is updated only after a successful pull sync. Failed sync attempts
leave the value unchanged.

What changed

- added `mirror_last_sync_at` to the repository API response
- updated pull mirror sync flow to persist the timestamp only on
successful sync
- kept `mirror_updated` behavior unchanged for queue/scheduling purposes

`mirror_updated` is currently tied to mirror queue behavior, so it
cannot safely represent the last successful sync time. The new field
makes that state explicit for API consumers without changing scheduling
semantics.

---------

Signed-off-by: pomidorry <106489913+Pomidorry@users.noreply.github.com>
Signed-off-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: Claude (Opus 4.7) <noreply@anthropic.com>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: Giteabot <teabot@gitea.io>

models/migrations/migrations.go

@@ -409,6 +409,7 @@ func prepareMigrationTasks() []*migration {
 		// Gitea 1.26.0 ends at migration ID number 330 (database version 331)
 
 		newMigration(331, "Add ActionRunAttempt model and related action fields", v1_27.AddActionRunAttemptModel),
+		newMigration(332, "Add last_sync_unix to mirror", v1_27.AddLastSyncUnixToMirror),
 	}
 	return preparedMigrations
 }

models/migrations/v1_27/v332.go

@@ -0,0 +1,21 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package v1_27
+
+import "xorm.io/xorm"
+
+type mirrorWithLastSyncUnix struct {
+	LastSyncUnix int64 `xorm:"INDEX"`
+}
+
+func (mirrorWithLastSyncUnix) TableName() string {
+	return "mirror"
+}
+
+func AddLastSyncUnixToMirror(x *xorm.Engine) error {
+	_, err := x.SyncWithOptions(xorm.SyncOptions{
+		IgnoreDropIndices: true,
+	}, new(mirrorWithLastSyncUnix))
+	return err
+}

models/repo/mirror.go

@@ -27,6 +27,7 @@ type Mirror struct {
 
 	UpdatedUnix    timeutil.TimeStamp `xorm:"INDEX"`
 	NextUpdateUnix timeutil.TimeStamp `xorm:"INDEX"`
+	LastSyncUnix   timeutil.TimeStamp `xorm:"INDEX"`
 
 	LFS         bool   `xorm:"lfs_enabled NOT NULL DEFAULT false"`
 	LFSEndpoint string `xorm:"lfs_endpoint TEXT"`

modules/structs/repo.go

@@ -125,10 +125,12 @@ type Repository struct {
 	// ObjectFormatName of the underlying git repository
 	ObjectFormatName ObjectFormatName `json:"object_format_name"`
 	// swagger:strfmt date-time
-	MirrorUpdated time.Time     `json:"mirror_updated"`
-	RepoTransfer  *RepoTransfer `json:"repo_transfer,omitempty"`
-	Topics        []string      `json:"topics"`
-	Licenses      []string      `json:"licenses"`
+	MirrorUpdated time.Time `json:"mirror_updated"`
+	// swagger:strfmt date-time
+	MirrorLastSyncAt time.Time     `json:"mirror_last_sync_at"`
+	RepoTransfer     *RepoTransfer `json:"repo_transfer,omitempty"`
+	Topics           []string      `json:"topics"`
+	Licenses         []string      `json:"licenses"`
 }
 
 // CreateRepoOption options when creating repository

services/convert/repository.go

@@ -152,11 +152,13 @@ func innerToRepo(ctx context.Context, repo *repo_model.Repository, permissionInR
 
 	mirrorInterval := ""
 	var mirrorUpdated time.Time
+	var lastSync time.Time
 	if repo.IsMirror {
 		pullMirror, err := repo_model.GetMirrorByRepoID(ctx, repo.ID)
 		if err == nil {
 			mirrorInterval = pullMirror.Interval.String()
 			mirrorUpdated = pullMirror.UpdatedUnix.AsTime()
+			lastSync = pullMirror.LastSyncUnix.AsTime()
 		}
 	}
 
@@ -247,6 +249,7 @@ func innerToRepo(ctx context.Context, repo *repo_model.Repository, permissionInR
 		DefaultTargetBranch:           defaultTargetBranch,
 		AvatarURL:                     repo.AvatarLink(ctx),
 		Internal:                      !repo.IsPrivate && repo.Owner.Visibility == api.VisibleTypePrivate,
+		MirrorLastSyncAt:              lastSync,
 		MirrorInterval:                mirrorInterval,
 		MirrorUpdated:                 mirrorUpdated,
 		RepoTransfer:                  transfer,

services/mirror/mirror_pull.go

@@ -305,6 +305,7 @@ func SyncPullMirror(ctx context.Context, repoID int64) bool {
 
 	log.Trace("SyncMirrors [repo: %-v]: Scheduling next update", m.Repo)
 	m.ScheduleNextUpdate()
+	m.LastSyncUnix = m.UpdatedUnix
 	if err = repo_model.UpdateMirror(ctx, m); err != nil {
 		log.Error("SyncMirrors [repo: %-v]: failed to UpdateMirror with next update date: %v", m.Repo, err)
 		return false

templates/swagger/v1_json.tmpl

@@ -29039,6 +29039,11 @@
           "type": "string",
           "x-go-name": "MirrorInterval"
         },
+        "mirror_last_sync_at": {
+          "type": "string",
+          "format": "date-time",
+          "x-go-name": "MirrorLastSyncAt"
+        },
         "mirror_updated": {
           "type": "string",
           "format": "date-time",

templates/swagger/v1_openapi3_json.tmpl

@@ -9292,6 +9292,11 @@
             "type": "string",
             "x-go-name": "MirrorInterval"
           },
+          "mirror_last_sync_at": {
+            "format": "date-time",
+            "type": "string",
+            "x-go-name": "MirrorLastSyncAt"
+          },
           "mirror_updated": {
             "format": "date-time",
             "type": "string",

tests/integration/mirror_pull_test.go

@@ -93,6 +93,9 @@ func TestMirrorPull(t *testing.T) {
 	ok := mirror_service.SyncPullMirror(ctx, mirrorRepo.ID)
 	assert.True(t, ok)
 
+	mirror := unittest.AssertExistsAndLoadBean(t, &repo_model.Mirror{RepoID: mirrorRepo.ID})
+	assert.Equal(t, mirror.UpdatedUnix, mirror.LastSyncUnix)
+
 	// actually there is a tag in the source repo, so after "sync", that tag will also come into the mirror
 	initCount++
 
@@ -110,4 +113,14 @@ func TestMirrorPull(t *testing.T) {
 	count, err = db.Count[repo_model.Release](t.Context(), findOptions)
 	assert.NoError(t, err)
 	assert.Equal(t, initCount, count)
+
+	mirror = unittest.AssertExistsAndLoadBean(t, &repo_model.Mirror{RepoID: mirrorRepo.ID})
+	lastMirrorSync := mirror.LastSyncUnix
+	assert.NoError(t, mirror_service.UpdateAddress(ctx, mirror, repoPath+"-missing"))
+
+	ok = mirror_service.SyncPullMirror(ctx, mirrorRepo.ID)
+	assert.False(t, ok)
+
+	mirror = unittest.AssertExistsAndLoadBean(t, &repo_model.Mirror{RepoID: mirrorRepo.ID})
+	assert.Equal(t, lastMirrorSync, mirror.LastSyncUnix)
 }