log

Documentation

Overview

Package log implements functionality to write workflow log commands from within a GitHub action.

See https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions

Index

• func IsDebug() bool
• type Annotation
  • func File(file string) Annotation
  • func Lines(start, end uint) Annotation
  • func Span(start, end uint) Annotation
  • func Title(title string) Annotation
• type Logger
  • func New(out io.Writer) Logger
  • func (l Logger) Debug(format string, a ...any)
  • func (l Logger) EndGroup()
  • func (l Logger) Error(message string, annotations ...Annotation)
  • func (l Logger) Mask(str string)
  • func (l Logger) Notice(message string, annotations ...Annotation)
  • func (l Logger) StartGroup(title string)
  • func (l Logger) Warning(message string, annotations ...Annotation)
  • func (l Logger) WithGroup(title string, fn func())

Functions

func IsDebug

func IsDebug() bool

IsDebug reports whether the actions runner is running in debug mode (${{ runner.debug }}) such that logs written with Logger.Debug will be visible.

See https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging

Types

type Annotation

type Annotation interface {
	// contains filtered or unexported methods
}

Annotation is a log command annotation.

func File

func File(file string) Annotation

File associates a source file with the annotation.

func Lines

func Lines(start, end uint) Annotation

Lines associates a span of lines in a source file with the annotation.

If the annotation does not already have File information when Lines is called the line information is omitted from the annotation i.e. you can't have lines but no file.

If start or end < 1, the default of 1 is used. Likewise if end < start, start is used as the end.

func Span

func Span(start, end uint) Annotation

Span associates a span of columns on a single line with the annotation.

If the annotation does not already have File information when Span is called the span information is omitted from the annotation i.e. you can't have span but no file.

If start or end < 1, column span information will be omitted from the annotation. Likewise if end < start.

If the caller has previously used Lines and the start and end line of the span are different, column span information is omitted from the annotation. This is an internal GitHub constraint.

func Title

func Title(title string) Annotation

Title adds a title to the log command annotation.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is the actions logger, it maintains no state other than an io.Writer which is where the logs will be printed.

func New

func New(out io.Writer) Logger

New returns a new Logger configured to write to out.

Correct usage in GitHub Actions sets out to os.Stdout, but specifying the writer can be handy for unit tests in your action code.

logger := log.New(os.Stdout)

func (Logger) Debug

func (l Logger) Debug(format string, a ...any)

Debug writes a formatted debug message to the workflow log.

The signature is analogous to fmt.Printf allowing format verbs and message formatting. It is not necessary to append a final newline to format.

If the format arguments are omitted, format will be treated as a verbatim string and passed straight through.

This will only be seen if $RUNNER_DEBUG (or ${{ runner.debug }}) is set which can be controlled by the person running the action.

Generally, this is done after a failed run with the "run with debug logs" option enabled.

See https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging

func (Logger) EndGroup

func (l Logger) EndGroup()

EndGroup ends an expandable log group.

Usage is typically deferred, see Logger.StartGroup for more info.

func (Logger) Error

func (l Logger) Error(message string, annotations ...Annotation)

Error writes a error message to the workflow log.

If message is the empty string "", nothing will be logged.

Additionally, the caller can configure source file annotation whereby the log will be associated with a particular file, line, column etc. of source. This is done by passing in one or more Annotation functions that configure this behaviour.

The annotations are all optional, and will only be added to the log message if they are explicitly set by the caller. If no annotations are passed, the log will simply be the message string.

func (Logger) Mask

func (l Logger) Mask(str string)

Mask redacts a string or environment variable, preventing it from being printed in the workflow logs.

When masked, the string or variable is replaced by `*` characters in subsequent logs. If str is the empty string "", nothing will be logged.

See https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#masking-a-value-in-a-log

logger := log.New(os.Stdout)
logger.Mask("$MY_SECRET") // Prevent the env var MY_SECRET from being logged
logger.Mask("a string") // Prevent any subsequent occurrences of "a string" from being logged

func (Logger) Notice

func (l Logger) Notice(message string, annotations ...Annotation)

Notice writes a notice message to the workflow log.

If message is the empty string "", nothing will be logged.

Additionally, the caller can configure source file annotation whereby the log will be associated with a particular file, line, column etc. of source. This is done by passing in one or more Annotation functions that configure this behaviour.

The annotations are all optional, and will only be added to the log message if they are explicitly set by the caller. If no annotations are passed, the log will simply be the message string.

func (Logger) StartGroup

func (l Logger) StartGroup(title string)

StartGroup begins a new expandable group in the workflow log.

Anything printed between the call to StartGroup and the call to Logger.EndGroup will be contained within this group.

The caller is responsible for calling Logger.EndGroup after a group is started. Recommended usage is as follows:

func doInGroup(logger actions.Logger) {
	logger.StartGroup()
	defer logger.EndGroup()
	// ...
	// Do your grouped logic here, the group will be
	// closed as the function returns
}

If you want this to be handled automatically, use Logger.WithGroup and pass your logic as a closure.

If title is the empty string "", nothing will be logged. Title will also be trimmed of all leading and trailing whitespace.

See https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#grouping-log-lines

func (Logger) Warning

func (l Logger) Warning(message string, annotations ...Annotation)

Warning writes a warning message to the workflow log.

If message is the empty string "", nothing will be logged.

Additionally, the caller can configure source file annotation whereby the log will be associated with a particular file, line, column etc. of source. This is done by passing in one or more Annotation functions that configure this behaviour.

The annotations are all optional, and will only be added to the log message if they are explicitly set by the caller. If no annotations are passed, the log will simply be the message string.

func (Logger) WithGroup

func (l Logger) WithGroup(title string, fn func())

WithGroup executes the provided closure fn inside an expandable group in the workflow log.

It automatically handles calling Logger.StartGroup and Logger.EndGroup to ensure the group is created and stopped correctly.

Anything printed by fn will be contained within the created group. If title is the empty string "", nothing will be logged.