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 ¶
- Constants
- Variables
- func AddToPath(value string) error
- func Debug(message string) error
- func EndGroup() error
- func Error(message string, options *WorkflowCommandOptions) error
- func GetBooleanInput(name string, opts *InputOptions) (bool, error)
- func GetInput(name string, opts *InputOptions) (string, error)
- func GetMultilineInput(name string, opts *InputOptions) ([]string, error)
- func MaskValue(value string) error
- func Notice(message string, options *WorkflowCommandOptions) error
- func SetEnv(key, value string) error
- func SetOutput(key, value string) error
- func SetState(key, value string) error
- func StartGroup(name string) error
- func Warning(message string, options *WorkflowCommandOptions) error
- type FileCommand
- type InputOptions
- type LookupEnvFunc
- type OsVersionInfo
- type PlatformInfo
- type ResumeCommandsFunc
- type Summary
- func (s *Summary) AddBreak()
- func (s *Summary) AddCodeBlock(code, lang string)
- func (s *Summary) AddDetails(label, content string)
- func (s *Summary) AddEOL()
- func (s *Summary) AddHeading(text string, level int)
- func (s *Summary) AddImage(src, alt string, options *SummaryImageOptions)
- func (s *Summary) AddLink(text, href string)
- func (s *Summary) AddList(items []string, ordered bool)
- func (s *Summary) AddQuote(text, cite string)
- func (s *Summary) AddRaw(text string, addEOL bool)
- func (s *Summary) AddSeparator()
- func (s *Summary) AddTable(rows []SummaryTableRow)
- func (s *Summary) ClearSummary() error
- func (s *Summary) EmptyBuffer()
- func (s *Summary) IsEmptyBuffer() bool
- func (s *Summary) String() string
- func (s *Summary) Write(options *SummaryWriteOptions) error
- type SummaryImageOptions
- type SummaryTableCell
- type SummaryTableRow
- type SummaryWriteOptions
- type WorkflowCommand
- type WorkflowCommandOptions
Examples ¶
Constants ¶
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" )
const ( DebugCommandStr = "debug" NoticeCommandStr = "notice" WarningCommandStr = "warning" ErrorCommandStr = "error" StartGroupCommandStr = "group" EndGroupCommandStr = "endgroup" MaskCommandStr = "add-mask" StopCommandsCommandStr = "stop-commands" )
const SummaryEnvVar = "GITHUB_STEP_SUMMARY"
SummaryEnvVar is the environment variable containing the summary file path.
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 ¶
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.
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.
var OsSpecificNewline string
Functions ¶
func AddToPath ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
LookupEnvFunc defines a function that returns the value of an environment variable and whether it was set.
type OsVersionInfo ¶
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 ¶
AddCodeBlock appends a code block (code) to the summary buffer with optional language (lang).
func (*Summary) AddDetails ¶
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 ¶
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 (*Summary) AddQuote ¶
AddQuote appends a blockquote to the summary buffer with optional citation.
func (*Summary) AddRaw ¶
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 ¶
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 ¶
IsEmptyBuffer reports whether the buffer is empty.
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.