Documentation
¶
Overview ¶
Package githubactions provides an SDK for authoring GitHub Actions in Go. It has no external dependencies and provides a Go-like interface for interacting with GitHub Actions' build system.
Index ¶
- Constants
- func AddMask(p string)
- func AddMatcher(p string)
- func AddPath(p string)
- func AddStepSummary(markdown string)
- func AddStepSummaryTemplate(tmpl string, data any) error
- func Debugf(msg string, args ...any)
- func EndGroup()
- func Errorf(msg string, args ...any)
- func Fatalf(msg string, args ...any)
- func GetIDToken(ctx context.Context, audience string) (string, error)
- func GetInput(i string) string
- func Group(t string)
- func Infof(msg string, args ...any)
- func IssueCommand(cmd *Command)
- func IssueFileCommand(cmd *Command)
- func Noticef(msg string, args ...any)
- func RemoveMatcher(o string)
- func SaveState(k, v string)
- func SetEnv(k, v string)
- func SetOutput(k, v string)
- func Warningf(msg string, args ...any)
- type Action
- func (c *Action) AddMask(p string)
- func (c *Action) AddMatcher(p string)
- func (c *Action) AddPath(p string)
- func (c *Action) AddStepSummary(markdown string)
- func (c *Action) AddStepSummaryTemplate(tmpl string, data any) error
- func (c *Action) Context() (*GitHubContext, error)
- func (c *Action) Debugf(msg string, args ...any)
- func (c *Action) EndGroup()
- func (c *Action) Errorf(msg string, args ...any)
- func (c *Action) Fatalf(msg string, args ...any)
- func (c *Action) GetIDToken(ctx context.Context, audience string) (string, error)
- func (c *Action) GetInput(i string) string
- func (c *Action) Getenv(key string) string
- func (c *Action) Group(t string)
- func (c *Action) Infof(msg string, args ...any)
- func (c *Action) IssueCommand(cmd *Command)
- func (c *Action) IssueFileCommand(cmd *Command)
- func (c *Action) Noticef(msg string, args ...any)
- func (c *Action) RemoveMatcher(o string)
- func (c *Action) SaveState(k, v string)
- func (c *Action) SetEnv(k, v string)
- func (c *Action) SetOutput(k, v string)
- func (c *Action) Warningf(msg string, args ...any)
- func (c *Action) WithFieldsMap(m map[string]string) *Action
- func (c *Action) WithFieldsSlice(f []string) *Action
- type Command
- type CommandProperties
- type GetenvFunc
- type GitHubContext
- type Option
Examples ¶
- Action.AddMask
- Action.AddPath
- Action.AddStepSummary
- Action.AddStepSummaryTemplate
- Action.Debugf
- Action.Debugf (FieldsMap)
- Action.Debugf (FieldsSlice)
- Action.EndGroup
- Action.Errorf
- Action.Errorf (FieldsMap)
- Action.Errorf (FieldsSlice)
- Action.GetIDToken
- Action.GetInput
- Action.Group
- Action.SetEnv
- Action.SetOutput
- Action.Warningf
- Action.Warningf (FieldsMap)
- Action.Warningf (FieldsSlice)
- New
Constants ¶
const EOF = "\n"
Variables ¶
This section is empty.
Functions ¶
func AddMask ¶
func AddMask(p string)
AddMask adds a new field mask for the given string "p". After called, future attempts to log "p" will be replaced with "***" in log output.
func AddStepSummary ¶ added in v1.0.0
func AddStepSummary(markdown string)
AddStepSummary writes the given markdown to the job summary. If a job summary already exists, this value is appended.
func AddStepSummaryTemplate ¶ added in v1.0.0
AddStepSummaryTemplate adds a summary template by parsing the given Go template using html/template with the given input data. See AddStepSummary for caveats.
This primarily exists as a convenience function that renders a template.
func Debugf ¶
Debugf prints a debug-level message. The arguments follow the standard Printf arguments.
func Errorf ¶
Errorf prints a error-level message. The arguments follow the standard Printf arguments.
func Fatalf ¶
Fatalf prints a error-level message and exits. This is equivalent to Errorf followed by os.Exit(1).
func GetIDToken ¶ added in v0.5.0
GetIDToken returns the GitHub OIDC token from the GitHub Actions runtime.
func Group ¶
func Group(t string)
Group starts a new collapsable region up to the next ungroup invocation.
func Infof ¶ added in v0.4.0
Infof prints a info-level message. The arguments follow the standard Printf arguments.
func IssueCommand ¶ added in v0.3.0
func IssueCommand(cmd *Command)
IssueCommand issues an arbitrary GitHub actions Command.
func IssueFileCommand ¶ added in v0.3.0
func IssueFileCommand(cmd *Command)
IssueFileCommand issues a new GitHub actions Command using environment files.
func Noticef ¶ added in v1.1.0
Noticef prints a notice-level message. The arguments follow the standard Printf arguments.
func RemoveMatcher ¶
func RemoveMatcher(o string)
RemoveMatcher removes a matcher with the given owner name.
Types ¶
type Action ¶
type Action struct {
// contains filtered or unexported fields
}
Action is an internal wrapper around GitHub Actions' output and magic strings.
func New ¶
New creates a new wrapper with helpers for outputting information in GitHub actions format.
Example ¶
a = githubactions.New()
Output:
func WithFieldsMap ¶
WithFieldsMap includes the provided fields in log output. The fields in "m" are automatically converted to k=v pairs and sorted.
func WithFieldsSlice ¶
WithFieldsSlice includes the provided fields in log output. "f" must be a slice of k=v pairs. The given slice will be sorted.
func (*Action) AddMask ¶
AddMask adds a new field mask for the given string "p". After called, future attempts to log "p" will be replaced with "***" in log output. It panics if it cannot write to the output stream.
Example ¶
a := githubactions.New() a.AddMask("my-password")
Output:
func (*Action) AddMatcher ¶
AddMatcher adds a new matcher with the given file path. It panics if it cannot write to the output stream.
func (*Action) AddPath ¶
AddPath adds the string "p" to the path for the invocation. It panics if it cannot write to the output file.
https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#adding-a-system-path https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/
Example ¶
a := githubactions.New() a.AddPath("/tmp/myapp")
Output:
func (*Action) AddStepSummary ¶ added in v1.0.0
AddStepSummary writes the given markdown to the job summary. If a job summary already exists, this value is appended.
https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/
Example ¶
a := githubactions.New() a.AddStepSummary(` ## Heading - :rocket: - :moon: `)
Output:
func (*Action) AddStepSummaryTemplate ¶ added in v1.0.0
AddStepSummaryTemplate adds a summary template by parsing the given Go template using html/template with the given input data. See AddStepSummary for caveats.
This primarily exists as a convenience function that renders a template.
Example ¶
a := githubactions.New() if err := a.AddStepSummaryTemplate(` ## Heading - {{.Input}} - :moon: `, map[string]string{ "Input": ":rocket:", }); err != nil { // handle error }
Output:
func (*Action) Context ¶ added in v1.0.0
func (c *Action) Context() (*GitHubContext, error)
Context returns the context of current action with the payload object that triggered the workflow
func (*Action) Debugf ¶
Debugf prints a debug-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.
Example ¶
a := githubactions.New() a.Debugf("a debug message")
Output:
Example (FieldsMap) ¶
a := githubactions.New() m := map[string]string{ "file": "app.go", "line": "100", } a.WithFieldsMap(m).Debugf("a debug message")
Output:
Example (FieldsSlice) ¶
a := githubactions.New() s := []string{"file=app.go", "line=100"} a.WithFieldsSlice(s).Debugf("a debug message")
Output:
func (*Action) EndGroup ¶
func (c *Action) EndGroup()
EndGroup ends the current group. It panics if it cannot write to the output stream.
Example ¶
a := githubactions.New() a.Group("My group") // work a.EndGroup()
Output:
func (*Action) Errorf ¶
Errorf prints a error-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.
Example ¶
a := githubactions.New() a.Errorf("an error message")
Output:
Example (FieldsMap) ¶
a := githubactions.New() m := map[string]string{ "file": "app.go", "line": "100", } a.WithFieldsMap(m).Errorf("an error message")
Output:
Example (FieldsSlice) ¶
a := githubactions.New() s := []string{"file=app.go", "line=100"} a.WithFieldsSlice(s).Errorf("an error message")
Output:
func (*Action) Fatalf ¶
Fatalf prints a error-level message and exits. This is equivalent to Errorf followed by os.Exit(1).
func (*Action) GetIDToken ¶ added in v0.5.0
GetIDToken returns the GitHub OIDC token from the GitHub Actions runtime.
Example ¶
ctx := context.Background() a := githubactions.New() token, err := a.GetIDToken(ctx, "my-aud") if err != nil { // handle error } _ = token
Output:
func (*Action) GetInput ¶
GetInput gets the input by the given name. It returns the empty string if the input is not defined.
Example ¶
a := githubactions.New() a.GetInput("foo")
Output:
func (*Action) Getenv ¶ added in v0.5.3
Getenv retrieves the value of the environment variable named by the key. It uses an internal function that can be set with `WithGetenv`.
func (*Action) Group ¶
Group starts a new collapsable region up to the next ungroup invocation. It panics if it cannot write to the output stream.
Example ¶
a := githubactions.New() a.Group("My group")
Output:
func (*Action) Infof ¶ added in v0.4.0
Infof prints message to stdout without any level annotations. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.
func (*Action) IssueCommand ¶ added in v0.3.0
IssueCommand issues a new GitHub actions Command. It panics if it cannot write to the output stream.
func (*Action) IssueFileCommand ¶ added in v0.3.0
IssueFileCommand issues a new GitHub actions Command using environment files. It panics if writing to the file fails.
The TypeScript equivalent function:
IssueFileCommand currently ignores the 'CommandProperties' field provided with the 'Command' argument as it's scope is unclear in the current TypeScript implementation.
func (*Action) Noticef ¶ added in v0.5.1
Noticef prints a notice-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.
func (*Action) RemoveMatcher ¶
RemoveMatcher removes a matcher with the given owner name. It panics if it cannot write to the output stream.
func (*Action) SaveState ¶
SaveState saves state to be used in the "finally" post job entry point. It panics if it cannot write to the output stream.
On 2022-10-11, GitHub deprecated "::save-state name=<k>::<v>" in favor of environment files.
func (*Action) SetEnv ¶
SetEnv sets an environment variable. It panics if it cannot write to the output file.
https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/
Example ¶
a := githubactions.New() a.SetEnv("MY_THING", "my value")
Output:
func (*Action) SetOutput ¶
SetOutput sets an output parameter. It panics if it cannot write to the output stream.
On 2022-10-11, GitHub deprecated "::set-output name=<k>::<v>" in favor of environment files.
Example ¶
a := githubactions.New() a.SetOutput("filepath", "/tmp/file-xyz1234")
Output:
func (*Action) Warningf ¶
Warningf prints a warning-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.
Example ¶
a := githubactions.New() a.Warningf("a warning message")
Output:
Example (FieldsMap) ¶
a := githubactions.New() m := map[string]string{ "file": "app.go", "line": "100", } a.WithFieldsMap(m).Warningf("a warning message")
Output:
Example (FieldsSlice) ¶
a := githubactions.New() s := []string{"file=app.go", "line=100"} a.WithFieldsSlice(s).Warningf("a warning message")
Output:
func (*Action) WithFieldsMap ¶
WithFieldsMap includes the provided fields in log output. The fields in "m" are automatically converted to k=v pairs and sorted.
func (*Action) WithFieldsSlice ¶
WithFieldsSlice includes the provided fields in log output. "f" must be a slice of k=v pairs. The given slice will be sorted. It panics if any of the string in the given slice does not construct a valid 'key=value' pair.
type Command ¶ added in v0.3.0
type Command struct { Name string Message string Properties CommandProperties }
Command can be issued by a GitHub action by writing to `stdout` with following format.
::name key=value,key=value::message
Examples: ::warning::This is the message ::set-env name=MY_VAR::some value
type CommandProperties ¶ added in v0.3.0
CommandProperties is a named "map[string]string" type to hold key-value pairs passed to an actions command.
func (*CommandProperties) String ¶ added in v0.3.0
func (props *CommandProperties) String() string
String encodes the CommandProperties to a string as comma separated 'key=value' pairs. The pairs are joined in a chronological order.
type GetenvFunc ¶ added in v0.4.0
GetenvFunc is an abstraction to make tests feasible for commands that interact with environment variables.
type GitHubContext ¶ added in v1.0.0
type GitHubContext struct { Action string `env:"GITHUB_ACTION"` ActionPath string `env:"GITHUB_ACTION_PATH"` ActionRepository string `env:"GITHUB_ACTION_REPOSITORY"` Actions bool `env:"GITHUB_ACTIONS"` Actor string `env:"GITHUB_ACTOR"` APIURL string `env:"GITHUB_API_URL,default=https://api.github.com"` BaseRef string `env:"GITHUB_BASE_REF"` Env string `env:"GITHUB_ENV"` EventName string `env:"GITHUB_EVENT_NAME"` EventPath string `env:"GITHUB_EVENT_PATH"` GraphqlURL string `env:"GITHUB_GRAPHQL_URL,default=https://api.github.com/graphql"` HeadRef string `env:"GITHUB_HEAD_REF"` Job string `env:"GITHUB_JOB"` Path string `env:"GITHUB_PATH"` Ref string `env:"GITHUB_REF"` RefName string `env:"GITHUB_REF_NAME"` RefProtected bool `env:"GITHUB_REF_PROTECTED"` RefType string `env:"GITHUB_REF_TYPE"` // Repository is the owner and repository name. For example, octocat/Hello-World // It is not recommended to use this field to acquire the repository name // but to use the Repo method instead. Repository string `env:"GITHUB_REPOSITORY"` // RepositoryOwner is the repository owner. For example, octocat // It is not recommended to use this field to acquire the repository owner // but to use the Repo method instead. RepositoryOwner string `env:"GITHUB_REPOSITORY_OWNER"` RetentionDays int64 `env:"GITHUB_RETENTION_DAYS"` RunAttempt int64 `env:"GITHUB_RUN_ATTEMPT"` RunID int64 `env:"GITHUB_RUN_ID"` RunNumber int64 `env:"GITHUB_RUN_NUMBER"` ServerURL string `env:"GITHUB_SERVER_URL,default=https://github.com"` SHA string `env:"GITHUB_SHA"` StepSummary string `env:"GITHUB_STEP_SUMMARY"` Workflow string `env:"GITHUB_WORKFLOW"` Workspace string `env:"GITHUB_WORKSPACE"` // Event is populated by parsing the file at EventPath, if it exists. Event map[string]any }
GitHubContext of current workflow.
See: https://docs.github.com/en/actions/learn-github-actions/environment-variables
func Context ¶ added in v1.0.0
func Context() (*GitHubContext, error)
func (*GitHubContext) Repo ¶ added in v1.1.0
func (c *GitHubContext) Repo() (string, string)
Repo returns the username of the repository owner and repository name.
type Option ¶ added in v0.4.0
Option is a modifier for an Action.
func WithFields ¶ added in v0.4.0
func WithFields(fields CommandProperties) Option
WithFields sets the extra command field on an Action.
func WithGetenv ¶ added in v0.4.0
func WithGetenv(getenv GetenvFunc) Option
WithGetenv sets the `Getenv` function on an Action. By default, this will be `os.Getenv` from the standard library.
func WithHTTPClient ¶ added in v0.5.0
WithHTTPClient sets a custom HTTP client on the action. This is only used when the action makes output HTTP requests (such as generating an OIDC token).
func WithWriter ¶ added in v0.4.0
WithWriter sets the writer function on an Action. By default, this will be `os.Stdout` from the standard library.