nprasad2077/docs
1
1
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-09-18 12:08:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Correct audit logging actors, warning and coverage

Browse Source 
The system actor names did not match what Gitea records, the disabled
warning only shows on the admin page, and the recorded/not recorded lists
overstated login and issue edit coverage while missing user status changes.

Co-Authored-By: Claude (Opus 5) <[email protected]>
This commit is contained in:
silverwind
2026-09-18 03:14:54 +02:00
co-authored by Claude
parent 240a2840a4
commit 1dd914792d
1 changed files with 31 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/administration/audit-logging.md
+31 -20
View File
@@ -36,8 +36,9 @@ before Gitea writes them into `app.ini`.
## View events
The Audit Log page is always available. When recording is disabled, it shows a
warning and still lists any events that were stored earlier.
The Audit Log pages are always available and still list any events that were
stored earlier. When recording is disabled, the site administration page also
shows a warning.
| Audience | Location | Events shown |
| --- | --- | --- |
@@ -47,8 +48,9 @@ warning and still lists any events that were stored earlier.
| Repository administrators | Repository settings → Audit Log (`/<owner>/<repo>/settings/audit_logs`) | Events scoped to that repository |
Each listing can be filtered by actor (username), action and origin, and sorted
by timestamp. Action filters accept an exact action or a family prefix such as
`user:impersonation` or `repository:webhook`.
by timestamp. The actor filter does not match the
[system actors](#actors-and-origins). Action filters accept an exact action or
a family prefix such as `user:impersonation` or `repository:webhook`.
Site administrators can download the current filtered result as JSONL
(newline-delimited JSON) from **Export JSONL**. The file name is
@@ -72,7 +74,9 @@ A recorded event contains:
- **Message**: a human-readable sentence rendered from a per-action template.
- **Metadata**: extra fields that fill the message template (token name, new
visibility, and so on). Secrets and token values are not stored.
- **IP address**: the client address of the request, when one exists.
- **IP address**: the client address of the request, when one exists. Events
triggered by a git push record the SSH client address for SSH pushes and
`127.0.0.1` for HTTP pushes.
- **Timestamp**: when the event was recorded.
An exported JSONL line looks like:
@@ -88,31 +92,36 @@ can parse it: `System started [Gitea {version}]`.
Most web and API requests pick up the signed-in user automatically.
Some entry points have no signed-in user. Those events use a dedicated actor:
Other entry points record a system actor:
- `CLI` for `gitea` command-line operations
- `AuthenticationSource` for authentication-source syncs and related background
work
- `Unknown` if the actor cannot be resolved; the event is still recorded
- `(gitea-cli)` for `gitea admin` commands and the `system:startup` and
`system:shutdown` events
- `(gitea-auth-source)` for authentication-source syncs and for users an
authentication source creates or updates at sign-in
- `gitea-actions` for Gitea Actions tasks
- `(deploy-key)` for pushes with a deploy key
- `(Cron)` for scheduled cron tasks
- `Unknown` when no actor can be resolved
Cron tasks and other background work use origin `system`. Git hooks and similar
non-interactive paths are attributed the same way.
Events of the `(gitea-cli)` actor use origin `cli`. Cron tasks, git hooks and
other background work use origin `system`.
## What is recorded
Events cover security-relevant changes, grouped by action family:
- **User**: create and delete, name, password, visibility, emails, 2FA,
WebAuthn, OpenID, external logins, access tokens, OAuth2 applications and
grants, SSH/GPG/principal keys, secrets, webhooks, impersonation, failed
two-factor authentication
- **User**: create and delete, admin, restricted and active status, name,
password and password reset requests, visibility, emails, authentication
source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2
applications and grants, SSH/GPG/principal keys, secrets, webhooks,
impersonation, failed two-factor authentication
- **Organization**: create and delete, name, visibility, members, teams,
OAuth2 applications, secrets, webhooks
- **Repository**: create, fork, archive, delete, rename, visibility, transfer,
mirrors, signing verification, collaborators and teams, default branch,
branch and tag protection, deploy keys, webhooks, secrets
- **Issues, pull requests, projects and wiki**: create, update, delete, comments
and merges
- **Issues and pull requests**: create, delete, comments and merges
- **Projects and wiki pages**: create, update and delete
- **Actions**: enable, disable and dispatch a workflow
- **System**: startup and shutdown, instance-wide webhooks, authentication
sources, instance-wide OAuth2 applications
@@ -123,8 +132,10 @@ and the original operation continues.
## What is not recorded
- Read-only access such as browsing, clone, fetch or API GET requests
- Successful password or SSH logins (use the [access log](logging-config.md)
and [Fail2ban Setup](fail2ban-setup.md) for authentication traffic)
- Logins, successful or failed, other than failed two-factor authentication
(use the [access log](logging-config.md) and
[Fail2ban Setup](fail2ban-setup.md) for authentication traffic)
- Edits to issues and pull requests
- Token or secret values
- Which SSH key a real user pushed with (deploy keys are named; ordinary SSH
user pushes are not)