feat: Add audit logging (#38189)

Co-authored-by: bircni <bircni@users.noreply.github.com>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

modules/setting/audit.go

@@ -0,0 +1,54 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package setting
+
+import (
+	"strings"
+	"time"
+
+	"gitea.dev/modules/log"
+)
+
+type AuditRecordOutput string
+
+const (
+	AuditRecordOutputDisabled AuditRecordOutput = "disabled"
+	AuditRecordOutputDatabase AuditRecordOutput = "database"
+)
+
+var Audit = struct {
+	RecordOutput  AuditRecordOutput `ini:"RECORD_OUTPUT"`
+	RetentionDays int64             `ini:"RETENTION_DAYS"`
+}{
+	RecordOutput:  AuditRecordOutputDisabled,
+	RetentionDays: 30,
+}
+
+func loadAuditFrom(rootCfg ConfigProvider) {
+	mustMapSetting(rootCfg, "audit", &Audit)
+
+	Audit.RecordOutput = AuditRecordOutput(strings.ToLower(strings.TrimSpace(string(Audit.RecordOutput))))
+	switch Audit.RecordOutput {
+	case "":
+		Audit.RecordOutput = AuditRecordOutputDisabled
+	case AuditRecordOutputDisabled, AuditRecordOutputDatabase:
+	default:
+		log.Error("Invalid [audit].RECORD_OUTPUT %q, audit records are disabled", Audit.RecordOutput)
+		Audit.RecordOutput = AuditRecordOutputDisabled
+	}
+
+	if Audit.RetentionDays < 0 {
+		Audit.RetentionDays = 0 // keep forever
+	}
+}
+
+// AuditRetentionPeriod is the age at which recorded events are pruned, zero meaning they are kept forever.
+func AuditRetentionPeriod() time.Duration {
+	return time.Duration(Audit.RetentionDays) * 24 * time.Hour
+}
+
+// AuditRecordEnabled reports whether audit events are recorded at all.
+func AuditRecordEnabled() bool {
+	return Audit.RecordOutput != AuditRecordOutputDisabled
+}

modules/setting/audit_test.go

@@ -0,0 +1,37 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package setting
+
+import (
+	"testing"
+
+	"gitea.dev/modules/test"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLoadAuditFrom(t *testing.T) {
+	for _, tc := range []struct {
+		name     string
+		cfg      string
+		expected AuditRecordOutput
+	}{
+		{name: "DisabledByDefault", cfg: "", expected: AuditRecordOutputDisabled},
+		{name: "Database", cfg: "[audit]\nRECORD_OUTPUT = Database\n", expected: AuditRecordOutputDatabase},
+		{name: "Empty", cfg: "[audit]\nRECORD_OUTPUT =\n", expected: AuditRecordOutputDisabled},
+		{name: "Invalid", cfg: "[audit]\nRECORD_OUTPUT = nonsense\n", expected: AuditRecordOutputDisabled},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			defer test.MockVariableValue(&Audit)()
+
+			cfg, err := NewConfigProviderFromData(tc.cfg)
+			require.NoError(t, err)
+			loadAuditFrom(cfg)
+
+			assert.Equal(t, tc.expected, Audit.RecordOutput)
+			assert.Equal(t, tc.expected != AuditRecordOutputDisabled, AuditRecordEnabled())
+		})
+	}
+}

modules/setting/setting.go

@@ -120,6 +120,7 @@ func loadCommonSettingsFrom(cfg ConfigProvider) error {
 	// WARNING: don't change the sequence except you know what you are doing.
 	loadRunModeFrom(cfg)
 	loadLogGlobalFrom(cfg)
+	loadAuditFrom(cfg)
 	loadServerFrom(cfg)
 	loadSSHFrom(cfg)