github-actions-logger

A logging.Logger subclass that emits GitHub Actions workflow commands when running in CI, and behaves like a normal logger everywhere else.

Installation

pip install github-actions-logger

Or with uv:

uv add github-actions-logger

Requires Python 3.12 or newer.

Usage

from github_actions_logger import Logger

log = Logger("my-app")

log.debug("Cache key: %s", key)
log.info("Deployed")
log.warning("Deprecated option used")
log.error("Build failed")

In GitHub Actions (detected via GITHUB_ACTIONS=true) these print:

::debug::Cache key: abc123
::notice::Deployed
::warning::Deprecated option used
::error::Build failed

Anywhere else, the calls go through standard logging, so handlers, levels and formatters work as usual.

Level mapping

exception() (or any call with exc_info) appends the traceback to the message.

Annotations

notice, warning and error messages can be attached to a file and line by passing the standard extra argument:

log.warning(
    "Unused import",
    extra={"title": "Lint", "file": "src/app.py", "line": 12, "end_line": 12, "col": 1, "end_column": 20},
)

::warning title=Lint,file=src/app.py,line=12,endLine=12,col=1,endColumn=20::Unused import

Missing or None keys and unrelated keys are ignored, and debug ignores them entirely since ::debug:: takes no properties. Outside CI, extra becomes attributes on the LogRecord, so a formatter can use it (for example %(file)s:%(line)s).

Grouping log lines

group() returns a context manager that wraps output in a collapsible log group:

with log.group("Install dependencies"):
    log.info("Resolving...")

::group::Install dependencies
::notice::Resolving...
::endgroup::

::endgroup:: is emitted even if the block raises. Outside CI, group() does nothing.

Overriding detection

CI detection happens once, when the logger is created. To force it on or off, pass in_ci:

Logger("my-app", in_ci=True)   # always emit workflow commands
Logger("my-app", in_ci=False)  # always use standard logging

Notes

• In CI, messages are written straight to stdout and bypass the logger's level and handlers. GitHub only displays ::debug:: lines when step debug logging is enabled (ACTIONS_STEP_DEBUG).
• Create the logger with Logger(...) directly. logging.setLoggerClass(Logger) plus logging.getLogger(name) works, but only passes name, so in_ci can't be set that way.

Development

uv run pytest

Runs the tests with a coverage report.