Lunny Xiaoandbircni
49e34813ae
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 <[email protected]> Reviewed-on: https://gitea.com/gitea/runner/pulls/1305 Reviewed-by: bircni <[email protected]>
3.2 KiB
Development
Job log line format
Gitea stores one log row per line and its web UI decodes the payload, so getting the encoding wrong never fails a test here, it only shows up in the browser.
A row cannot contain a real newline. FormatLog rewrites \n to a literal backslash-n and
truncates at 64 KiB on a byte boundary.
The payload of a line starting with a recognised prefix is decoded, with the escape set depending on the prefix:
| prefix | decodes |
|---|---|
##[error] ##[warning] ##[notice] ##[debug] ##[group] ##[endgroup] ##[add-matcher] |
%25 %0D %0A %3B %5D |
::error:: ::warning:: ::notice:: ::debug:: (with or without key=value properties), ::group:: ::endgroup:: ::add-matcher:: |
%25 %0D %0A |
##[command] [command], or no recognised prefix |
nothing |
Rules
- Emitting a command line? Escape the payload with
runner.EscapeCommandData. One escaper covers both forms: it escapes%first, so a literal%3Bbecomes%253Bthat the extra##[…]rules cannot match, and a raw;or]is never decoded. It is also what makes multi-line work,\nbecomes%0Aand the UI turns it back into a line break. - Forwarding a command from step output? Leave the payload alone, it arrived escaped and is decoded once. Decoding here double-decodes and destroys multi-line.
- No prefix? Do not escape, and split multi-line values into one row each.
- Interpolating a secret? Masking runs after escaping, so
AppendSecretMaskerregisters the encoded forms too. - Command properties also escape
%3Aand%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
loggingconfigures it. A dependency that callslogrus.SetOutputorSetLevelbreaks it, so checklogging.LogrusBridgeIntact()when adding or upgrading one. - Tests read what was logged with
logtest.NewLogger(), orlogtest.SetDefault(t)for the package functions.
Built-in actions
Each lives in internal/pkg/action/<name> and is registered in builtinActions in
act/runner/step_action_builtin.go.
End-to-end compatibility tests
make test-e2e runs the runner against E2E_GITEA_IMAGE. It defaults to the nightly image.
It requires Docker and is excluded from make test. CI runs stable and nightly variants in
parallel.
The suite shares one Gitea and regular runner. Cache and ephemeral scenarios use isolated
repository runners. A run path is <workflow>@<ref> and a log row is <timestamp>Z <payload>.