Help us shape the future of Go! Take the 2026 Go Developer Survey

core

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package core provides helpers for emitting GitHub Actions workflow commands and working with runner-provided files. Information on GitHub Workflow Commands are here: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands

Index

Examples

Constants

View Source
const (
	// GithubStateFilePathEnv points to the env var that stores the state file path.
	GithubStateFilePathEnv = "GITHUB_STATE"
	// EnvironmentVariableFilePathEnv points to the env var that stores the env file path.
	EnvironmentVariableFilePathEnv = "GITHUB_ENV"
	// OutputFilePathEnv points to the env var that stores the output file path.
	OutputFilePathEnv = "GITHUB_OUTPUT"
	// SystemPathFilePathEnv points to the env var that stores the PATH file path.
	SystemPathFilePathEnv = "GITHUB_PATH"
)
View Source
const (
	DebugCommandStr        = "debug"
	NoticeCommandStr       = "notice"
	WarningCommandStr      = "warning"
	ErrorCommandStr        = "error"
	StartGroupCommandStr   = "group"
	EndGroupCommandStr     = "endgroup"
	MaskCommandStr         = "add-mask"
	StopCommandsCommandStr = "stop-commands"
)
View Source
const SummaryEnvVar = "GITHUB_STEP_SUMMARY"

SummaryEnvVar is the environment variable containing the summary file path.

View Source
const WorkflowCommandString = "::"

WorkflowCommandString is the delimiter that wraps GitHub Actions workflow commands. https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#about-workflow-commands

Variables

View Source
var ErrInputRequired = errors.New("input required and not supplied")

ErrInputRequired is returned by GetInput, GetBooleanInput, and GetMultilineInput when an input is declared required but the resolved value is empty. Use errors.Is to test for this sentinel.

View Source
var ErrInvalidBooleanInput = errors.New("input does not meet YAML 1.2 \"Core Schema\" boolean specification")

ErrInvalidBooleanInput is returned by GetBooleanInput when the input value does not match any YAML 1.2 "Core Schema" boolean string ("true", "True", "TRUE", "false", "False", "FALSE"). Use errors.Is to test for this sentinel.

View Source
var OsSpecificNewline string

Functions

func AddToPath

func AddToPath(value string) error

AddToPath executes a GitHub Workflow command to add a directory to the system PATH for subsequent workflow steps. GitHub Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#adding-a-system-path

func Debug

func Debug(message string) error

Debug writes a debug message to stdout as a WorkflowCommand. GitHub Debug Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-a-debug-message

func EndGroup

func EndGroup() error

EndGroup closes the most recent collapsible log group. GitHub Group Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#grouping-log-lines

func Error

func Error(message string, options *WorkflowCommandOptions) error

Error writes an error message to stdout as a WorkflowCommand. GitHub Error Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-error-message

func GetBooleanInput

func GetBooleanInput(name string, opts *InputOptions) (bool, error)

GetBooleanInput reads a GitHub Actions input by name and interprets it as a boolean. It accepts only the YAML 1.2 "Core Schema" boolean strings: "true", "True", "TRUE" evaluate to true; "false", "False", "FALSE" evaluate to false. Any other value returns ErrInvalidBooleanInput (wrapped). GetBooleanInput propagates ErrInputRequired from GetInput when opts.Required is true. GitHub Actions Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/variables

func GetInput

func GetInput(name string, opts *InputOptions) (string, error)

GetInput reads a GitHub Actions input by name, applying the options in opts. The input is resolved from the environment variable INPUT_<NAME>, where <NAME> is the input name with spaces replaced by underscores and converted to uppercase. Hyphens in the name are preserved. If opts is nil it is treated as a zero InputOptions (not required, trim whitespace). GetInput returns ErrInputRequired (wrapped) when opts.Required is true and the input is unset or empty. GitHub Actions Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/variables

Example
os.Setenv("INPUT_NAME", "  Mona  ")
val, err := GetInput("name", nil)
if err != nil {
	fmt.Println("error:", err)
	return
}
fmt.Println(val)
Output:
Mona

func GetMultilineInput

func GetMultilineInput(name string, opts *InputOptions) ([]string, error)

GetMultilineInput reads a GitHub Actions input by name and splits the value on newlines. Empty lines are dropped from the result. Each line is trimmed of surrounding whitespace unless opts.TrimWhitespace points to false. GetMultilineInput returns a nil slice when the input is unset or resolves to no non-empty lines. GetMultilineInput propagates ErrInputRequired from GetInput when opts.Required is true. GitHub Actions Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/variables

func MaskValue

func MaskValue(value string) error

MaskValue instructs GitHub Actions to redact the provided value from logs. GitHub Mask Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#masking-a-value-in-a-log

func Notice

func Notice(message string, options *WorkflowCommandOptions) error

Notice writes a notice message to stdout as a WorkflowCommand. GitHub Notice Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-a-notice-message

func SetEnv

func SetEnv(key, value string) error

SetEnv executes a GitHub Workflow command to set an environment variable in subsequent workflows steps. GitHub Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-environment-variable

func SetOutput

func SetOutput(key, value string) error

SetOutput executes a GitHub Workflow command to set a step output. GitHub Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-output-parameter

func SetState

func SetState(key, value string) error

SetState executes a GitHub Workflow command to set a state parameter which is available to post-actions GitHub Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#sending-values-to-the-pre-and-post-actions

func StartGroup

func StartGroup(name string) error

StartGroup begins a collapsible log group. GitHub Group Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#grouping-log-lines

func Warning

func Warning(message string, options *WorkflowCommandOptions) error

Warning writes a warning message to stdout as a WorkflowCommand. GitHub Warning Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-a-warning-message

Types

type FileCommand

type FileCommand struct {
	Delimiter string
	Fs        afero.Fs
	FilePath  string
	Key       string
	Value     string
}

FileCommand represents a GitHub Actions file command targeting a specific file. Use SetEnv, SetOutput, SetState, or AddToPath to create and send file commands.

func (*FileCommand) Send

func (fc *FileCommand) Send() error

Send writes the FileCommand to its target file. GitHub Command Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#about-workflow-commands

type InputOptions

type InputOptions struct {
	// Required reports whether the input must be set.
	// GetInput returns [ErrInputRequired] when Required is true and the input is empty.
	Required bool
	// TrimWhitespace controls whitespace trimming.
	// A nil value (the default) or a pointer to true trims surrounding whitespace from the value.
	// A pointer to false preserves the raw value exactly as set in the environment.
	TrimWhitespace *bool
}

InputOptions controls how an input value is read.

type LookupEnvFunc

type LookupEnvFunc func(string) (string, bool)

LookupEnvFunc defines a function that returns the value of an environment variable and whether it was set.

type OsVersionInfo

type OsVersionInfo struct {
	Name    string
	Version string
}

OsVersionInfo holds operating system name and version information.

func GetLinuxOsInfo

func GetLinuxOsInfo() (OsVersionInfo, error)

GetLinuxOsInfo retrieves the Linux OsVersionInfo by executing lsb_release commands.

func GetMacOsInfo

func GetMacOsInfo() (OsVersionInfo, error)

GetMacOsInfo retrieves the macOS OsVersionInfo by executing sw_vers commands.

func GetWindowsOsInfo

func GetWindowsOsInfo() (OsVersionInfo, error)

GetWindowsOsInfo retrieves the Windows OsVersionInfo by executing PowerShell commands.

type PlatformInfo

type PlatformInfo struct {
	Name     string
	Platform string
	Arch     string
	Version  string
	// contains filtered or unexported fields
}

PlatformInfo holds detailed information about the current platform.

func GetPlatformInfo

func GetPlatformInfo() (PlatformInfo, error)

GetPlatformInfo retrieves detailed PlatformInfo about the current platform, including name, platform type, architecture, and version.

type ResumeCommandsFunc

type ResumeCommandsFunc func() error

func StopCommands

func StopCommands() (ResumeCommandsFunc, error)

StopCommands suspends workflow command processing and returns a ResumeCommandsFunc to re-enable it. GitHub Stop Commands Reference: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#stopping-and-starting-workflow-commands

type Summary

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

Summary holds buffered HTML content for the GitHub Actions job summary. https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary

var StepSummary *Summary

StepSummary is the process-wide Summary writer bound to the GitHub Actions job summary file.

Details on the GitHub Actions job summary are here: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#adding-a-job-summary

func NewSummary

func NewSummary(lookupEnvFunc LookupEnvFunc, fs afero.Fs) *Summary

NewSummary creates a Summary with the provided environment lookup and filesystem. If the summary file path is available, it is cached for writes. Similar to the GitHub provided actions toolkit, this does not panic if the summary file path is not available, but Summary.Write attempts will return an error.

func (*Summary) AddBreak

func (s *Summary) AddBreak()

AddBreak appends an HTML line break to the summary buffer.

func (*Summary) AddCodeBlock

func (s *Summary) AddCodeBlock(code, lang string)

AddCodeBlock appends a code block (code) to the summary buffer with optional language (lang).

func (*Summary) AddDetails

func (s *Summary) AddDetails(label, content string)

AddDetails appends a details HTML element to the summary buffer with a summary label and content.

func (*Summary) AddEOL

func (s *Summary) AddEOL()

AddEOL appends an OS-specific end-of-line marker to the buffer.

func (*Summary) AddHeading

func (s *Summary) AddHeading(text string, level int)

AddHeading appends an HTML heading to the shared StepSummary buffer. Level must be between 1 and 6; values outside this range default to 1.

func (*Summary) AddImage

func (s *Summary) AddImage(src, alt string, options *SummaryImageOptions)

AddImage appends an image element to the summary buffer with optional attributes.

func (s *Summary) AddLink(text, href string)

AddLink appends a hyperlink to the summary buffer.

func (*Summary) AddList

func (s *Summary) AddList(items []string, ordered bool)

AddList appends an unordered or ordered list to the summary buffer.

func (*Summary) AddQuote

func (s *Summary) AddQuote(text, cite string)

AddQuote appends a blockquote to the summary buffer with optional citation.

func (*Summary) AddRaw

func (s *Summary) AddRaw(text string, addEOL bool)

AddRaw appends raw text to the buffer and optionally appends an end-of-line.

func (*Summary) AddSeparator

func (s *Summary) AddSeparator()

AddSeparator appends a horizontal rule to the summary buffer.

func (*Summary) AddTable

func (s *Summary) AddTable(rows []SummaryTableRow)

AddTable appends an HTML table to the summary buffer.

func (*Summary) ClearSummary

func (s *Summary) ClearSummary() error

ClearSummary wipes both the buffer and the summary file contents.

func (*Summary) EmptyBuffer

func (s *Summary) EmptyBuffer()

EmptyBuffer resets the in-memory buffer without writing to disk.

func (*Summary) IsEmptyBuffer

func (s *Summary) IsEmptyBuffer() bool

IsEmptyBuffer reports whether the buffer is empty.

func (*Summary) String

func (s *Summary) String() string

String returns the current buffer contents.

func (*Summary) Write

func (s *Summary) Write(options *SummaryWriteOptions) error

Write flushes the buffer to the summary file, appending unless SummaryWriteOptions.Overwrite is set. The buffer is cleared after a successful write.

type SummaryImageOptions

type SummaryImageOptions struct {
	Width  string // HTML width attribute
	Height string // HTML height attribute
}

SummaryImageOptions configures the attributes for an image added via Summary.AddImage.

type SummaryTableCell

type SummaryTableCell struct {
	Data    string // cell content
	Header  bool   // render as <th> instead of <td>
	ColSpan string // HTML colspan attribute
	RowSpan string // HTML rowspan attribute
}

SummaryTableCell represents a cell in a summary table built via Summary.AddTable.

type SummaryTableRow

type SummaryTableRow []SummaryTableCell

SummaryTableRow represents a row of SummaryTableCell values in a summary table.

type SummaryWriteOptions

type SummaryWriteOptions struct {
	Overwrite bool // replace existing content instead of appending
}

SummaryWriteOptions configures how Summary.Write flushes the buffer to disk.

type WorkflowCommand

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

WorkflowCommand represents a formatted GitHub Actions workflow command using the WorkflowCommandString delimiter syntax.

GitHub Workflow Command Reference: https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#about-workflow-commands

func NewWorkflowCommand

func NewWorkflowCommand(w io.Writer, command string, properties map[string]string, message string) *WorkflowCommand

NewWorkflowCommand creates a WorkflowCommand targeting the given writer.

func (*WorkflowCommand) Send

func (wc *WorkflowCommand) Send() error

Send writes the workflow command to the provided writer. GitHub Workflow Command Reference: https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#about-workflow-commands

func (*WorkflowCommand) String

func (wc *WorkflowCommand) String() string

String renders the workflow command into the GitHub Actions command syntax. GitHub Workflow Command Reference: https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#about-workflow-commands

type WorkflowCommandOptions

type WorkflowCommandOptions struct {
	FileName    *string // source file path for the annotation
	StartLine   *int    // starting line number
	EndLine     *int    // ending line number
	Title       *string // annotation title
	StartColumn *int    // starting column number
	EndColumn   *int    // ending column number
}

WorkflowCommandOptions describes optional metadata for notice/warning/error commands.

func (*WorkflowCommandOptions) CmdProperties

func (wco *WorkflowCommandOptions) CmdProperties() map[string]string

CmdProperties converts the options into a property map for a WorkflowCommand.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL