From 49e34813ae7696b97bb3d4b900a8d3e56180b2d1 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Mon, 12 Oct 2026 06:52:14 +0000 Subject: [PATCH] docs: describe the logging package (#1305) Drop the logrus references from the docs and the config example, and add a Logging section to `DEVELOPMENT.md` on how to log and test logging. Stacked on https://gitea.com/gitea/runner/pulls/1304. Assisted-by: Codet Co-authored-by: bircni Reviewed-on: https://gitea.com/gitea/runner/pulls/1305 Reviewed-by: bircni --- DEVELOPMENT.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index accae3a7..d40c3f4b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -31,6 +31,23 @@ depending on the prefix: - Command *properties* also escape `%3A` and `%2C`, which the UI never decodes, so the reporter decodes exactly those two when folding a location into an annotation. +## Logging + +Log through `act/common/logging`; the linter rejects importing `log/slog` or logrus elsewhere. +A job's logger comes from `common.Logger(ctx)`; code with no job uses the package functions +(`logging.Infof`, `logging.With`). Both take printf-style messages, and `With("key", value)` adds +fields. + +- The process-wide logger masks the secrets of every live task, the job logger masks its own. + Going around either leaks them. +- Libraries that log through logrus's global logger are forwarded to the process-wide one, so they + follow its level and masking too. +- That forwarding only works while logrus's global logger is left as `logging` configures it. A + dependency that calls `logrus.SetOutput` or `SetLevel` breaks it, so check + `logging.LogrusBridgeIntact()` when adding or upgrading one. +- Tests read what was logged with `logtest.NewLogger()`, or `logtest.SetDefault(t)` for the + package functions. + ## Built-in actions Each lives in `internal/pkg/action/` and is registered in `builtinActions` in