Documentation
¶
Overview ¶
package githubactions contains types compatible with the data structures in GitHub Actions such as a GitHub Actions Workflow Step; common environment variables; parsing of $GITHUB_PATH files, $GITHUB_ENV files, and GitHub Actions Workflow commands; downloading GitHub Actions, and more. Such functionality is used by Forge, but is not specific to it.
Index ¶
- Constants
- Variables
- func APIURLFromBaseURL(base *url.URL) (*url.URL, error)
- func Expand(b []byte, expand ExpandFunc) (p []byte)
- func ExpandString(s string, expand ExpandFunc) string
- func GetGitHubAPIURL() *url.URL
- func GetGitHubServerURL() *url.URL
- func GetGitHubURL() *url.URL
- func GetGraphQLURL() *url.URL
- func GraphQLURLFromBaseURL(base *url.URL) (*url.URL, error)
- func OpenDirectoryMetadata(dir string) (_ io.Reader, err error)
- func OpenUsesMetadata(uses *Uses) (io.Reader, error)
- func ParseEnvFile(r io.Reader) (map[string]string, error)
- func ParsePathFile(r io.Reader) (string, error)
- type ExpandFunc
- type GitHubContext
- type GlobalContext
- type JobContext
- type JobContextContainer
- type JobContextService
- type Metadata
- type MetadataInput
- type MetadataOutput
- type MetadataRuns
- type NeedContext
- type RunnerContext
- type Step
- type StepContext
- type Uses
- type WorkflowCommand
- type WorkflowCommandWriter
Constants ¶
const ( ArchX86 = "X86" ArchX64 = "X64" ArchARM = "ARM" ArchARM64 = "ARM64" )
const ( // DefaultBranch is the default git branch to be used // if no other can be surmised. DefaultBranch = "main" // DefaultBranch is the default git origin to be used // if no other can be surmised. DefaultRemote = "origin" )
const ( EnvVarCI = "CI" EnvVarWorkflow = "GITHUB_WORKFLOW" EnvVarRunID = "GITHUB_RUN_ID" EnvVarRunNumber = "GITHUB_RUN_NUMBER" EnvVarRunAttempt = "GITHUB_RUN_ATTEMPT" EnvVarJob = "GITHUB_JOB" EnvVarAction = "GITHUB_ACTION" EnvVarActionPath = "GITHUB_ACTION_PATH" EnvVarActions = "GITHUB_ACTIONS" EnvVarActor = "GITHUB_ACTOR" EnvVarRepository = "GITHUB_REPOSITORY" EnvVarEventName = "GITHUB_EVENT_NAME" EnvVarEventPath = "GITHUB_EVENT_PATH" EnvVarWorkspace = "GITHUB_WORKSPACE" EnvVarSha = "GITHUB_SHA" EnvVarRef = "GITHUB_REF" EnvVarRefName = "GITHUB_REF_NAME" EnvVarRefProtected = "GITHUB_REF_PROTECTED" EnvVarRefType = "GITHUB_REF_TYPE" EnvVarHeadRef = "GITHUB_HEAD_REF" EnvVarBaseRef = "GITHUB_BASE_REF" EnvVarServerURL = "GITHUB_SERVER_URL" EnvVarAPIURL = "GITHUB_API_URL" EnvVarGraphQLURL = "GITHUB_GRAPHQL_URL" EnvVarRunnerName = "RUNNER_NAME" EnvVarRunnerOS = "RUNNER_OS" EnvVarRunnerArch = "RUNNER_ARCH" EnvVarRunnerTemp = "RUNNER_TEMP" EnvVarRunnerToolCache = "RUNNER_TOOL_CACHE" EnvVarEnv = "GITHUB_ENV" EnvVarPath = "GITHUB_PATH" EnvVarState = "GITHUB_STATE" EnvVarOutput = "GITHUB_OUTPUT" EnvVarToken = "GITHUB_TOKEN" //nolint:gosec EnvVarRepositoryOwner = "GITHUB_REPOSITORY_OWNER" EnvVarRetentionDays = "GITHUB_RETENTION_DAYS" EnvVarStepSummary = "GITHUB_STEP_SUMMARY" EnvVarActionRepository = "GITHUB_ACTION_REPOSITORY" )
const ( RunsUsingDockerImagePrefix = "docker://" RunsUsingDocker = "docker" RunsUsingComposite = "composite" RunsUsingNode12 = "node12" RunsUsingNode16 = "node16" RunsUsingNode20 = "node20" )
const ( OSLinux = "Linux" OSWindows = "Windows" OSDarwin = "macOS" )
const ( RefTypeTag = "tag" RefTypeBranch = "branch" )
const ( // SecretActionsStepDebug--see https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging. SecretActionsStepDebug = "ACTIONS_STEP_DEBUG" // SecretActionsRunnerDebug--see https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging. SecretActionsRunnerDebug = "ACTIONS_RUNNER_DEBUG" // SecretRunnerDebug--see https://github.com/actions/toolkit/blob/master/packages/core/src/core.ts#L118-L123. SecretRunnerDebug = "RUNNER_DEBUG" )
const ( CommandDebug = "debug" CommandGroup = "group" CommandEndGroup = "endgroup" CommandSaveState = "save-state" CommandSetOutput = "set-output" CommandNotice = "notice" CommandWarning = "warning" CommandError = "error" CommandAddMask = "add-mask" CommandAddPath = "add-path" CommandEcho = "echo" CommandStopCommands = "stop-commands" )
Variables ¶
var ActionYAMLFilenames = []string{"action.yml", "action.yaml"}
ActionYAMLFilenames holds the possible names of a GitHub Action metadata file.
Functions ¶
func Expand ¶
func Expand(b []byte, expand ExpandFunc) (p []byte)
Expand takes bytes and an ExpandFunc. Whenever it encounters a variable in the bytes, signified by e.g. "${{ example }}", it calls ExpandFunc with the variable name and replaces the variable with the result. It returns the fully expanded bytes.
func ExpandString ¶
func ExpandString(s string, expand ExpandFunc) string
ExpandString is a convenience method for Expanding strings. See Expand.
func GetGitHubAPIURL ¶
func GetGitHubServerURL ¶
func GetGitHubURL ¶
func GetGraphQLURL ¶
func ParseEnvFile ¶ added in v0.6.0
ParseEnvFile reads a GitHub Actions environment file e.g.
KEY1=value1 # SKIPPED=comment KEY2<<ghadelimiter_CC992248-87BA-41AF-BF33-A52DCE9681A6 value2 # For some security reason(s), @actions/core writes to the environment this way. ghadelimiter_CC992248-87BA-41AF-BF33-A52DCE9681A6
Types ¶
type ExpandFunc ¶
ExpandFunc takes a variable name and returns the variable value.
func (ExpandFunc) Expand ¶ added in v0.4.3
func (e ExpandFunc) Expand(b []byte) []byte
func (ExpandFunc) ExpandString ¶ added in v0.4.3
func (e ExpandFunc) ExpandString(s string) string
type GitHubContext ¶
type GitHubContext struct { Action string ActionPath string Actor string BaseRef string Event string EventName string EventPath string HeadRef string Job string Ref string RefName string RefProtected bool RefType string Repository string RepositoryOwner string RunID string RunNumber int64 RunAttempt int64 ServerURL string Sha string Token string Workflow string Workspace string }
GitHubContext stores all the values accessible through the...
${{ github }}
...context in workflow files.
func (*GitHubContext) GetString ¶
func (c *GitHubContext) GetString(key string) string
GetString allows *GitHubContext to be accessed "like a map", e.g. *GitHubContext.GetString("ref") returns *GitHubContext.Ref.
type GlobalContext ¶
type GlobalContext struct { GitHubContext *GitHubContext EnvContext map[string]string JobContext *JobContext StepsContext map[string]StepContext RunnerContext *RunnerContext InputsContext map[string]string SecretsContext map[string]string NeedsContext map[string]NeedContext }
GlobalContext stores all contexts accessible within a GitHub Action, i.e. the stuff you access...
${{ like.this }}
...in workflow files.
func NewGlobalContextFromEnv ¶
func NewGlobalContextFromEnv() *GlobalContext
NewGlobalContextFromEnv returns a *GlobalContext whose values are sourced from the environment as well as sensible defaults.
func NewGlobalContextFromPath ¶
func NewGlobalContextFromPath(path string) (*GlobalContext, error)
NewGlobalContextFromPath returns a *GlobalContext whose values are sourced from the git repository at the given path, the environment and some sensible defaults.
func (*GlobalContext) AddEnv ¶
func (c *GlobalContext) AddEnv(env map[string]string)
AddEnv adds the given environment variable map to its environment context.
func (*GlobalContext) DebugEnabled ¶ added in v0.15.1
func (c *GlobalContext) DebugEnabled() bool
func (*GlobalContext) EnableDebug ¶ added in v0.15.1
func (c *GlobalContext) EnableDebug() *GlobalContext
func (*GlobalContext) Env ¶
func (c *GlobalContext) Env() []string
Env returns the environment array for this *GlobalContext.
func (*GlobalContext) GetString ¶
func (c *GlobalContext) GetString(key string) string
GetString allows *GlobalContext to be accessed "like a map", e.g. *GlobalContext.GetString("env.EXAMPLE") returns *GlobalContext.EnvContext["EXAMPLE"].
type JobContext ¶
type JobContext struct { Container *JobContextContainer Services map[string]JobContextService Status string }
JobContext stores all the values accessible through the...
${{ job }}
...context in workflow files.
func (*JobContext) GetString ¶
func (c *JobContext) GetString(key string) string
GetString allows *JobContext to be accessed "like a map", e.g. *JobContext.GetString("container.id") returns *JobContext.Container.ID.
type JobContextContainer ¶
JobContextContainer stores all the values accessible through the...
${{ job.container }}
...context in workflow files.
type JobContextService ¶
JobContextService stores all the values accessible through the...
${{ job.service }}
...context in workflow files.
type Metadata ¶
type Metadata struct { Name string `json:"name,omitempty"` Author string `json:"author,omitempty"` Description string `json:"description,omitempty"` Inputs map[string]MetadataInput `json:"inputs,omitempty"` Output map[string]MetadataOutput `json:"output,omitempty"` Runs *MetadataRuns `json:"runs,omitempty"` }
func DownloadAction ¶ added in v0.6.0
DownloadAction takes a Uses reference and returns the corresponding GitHub Action Metadata and a tarball of the GitHub Action repository.
func GetUsesMetadata ¶
func (*Metadata) InputsFromWith ¶
func (*Metadata) IsComposite ¶
func (*Metadata) IsDockerfile ¶
type MetadataInput ¶
type MetadataOutput ¶
type MetadataOutput struct {
Description string `json:"description,omitempty"`
}
type MetadataRuns ¶
type MetadataRuns struct { Plugin string `json:"plugin,omitempty"` Using string `json:"using,omitempty"` Pre string `json:"pre,omitempty"` Main string `json:"main,omitempty"` Post string `json:"post,omitempty"` Image string `json:"image,omitempty"` PreEntrypoint string `json:"pre_entrypoint,omitempty"` Entrypoint string `json:"entrypoint,omitempty"` PostEntrypoint string `json:"post_entrypoint,omitempty"` Args []string `json:"args,omitempty"` Env map[string]string `json:"env,omitempty"` Steps []Step `json:"steps,omitempty"` }
type NeedContext ¶
Needontext stores all the values accessible through the...
TODO: needs? ${{ need }}
...context in workflow files.
func (*NeedContext) GetString ¶
func (c *NeedContext) GetString(key string) string
GetString allows *NeedContext to be accessed "like a map", e.g. *NeedContext.GetString("outputs.digest") returns *NeedContext.Outputs["digest"].
type RunnerContext ¶
RunnerContext stores all the values accessible through the...
${{ runner }}
...context in workflow files.
func (*RunnerContext) GetString ¶
func (c *RunnerContext) GetString(key string) string
GetString allows *RunnerContext to be accessed "like a map", e.g. *RunnerContext.GetString("os") returns *RunnerContext.OS.
type Step ¶
type Step struct { Shell string `json:"shell,omitempty"` If string `json:"if,omitempty"` Name string `json:"name,omitempty"` ID string `json:"id,omitempty"` Env map[string]string `json:"env,omitempty"` WorkingDir string `json:"working_dir,omitempty"` Uses string `json:"uses,omitempty"` With map[string]string `json:"with,omitempty"` Run string `json:"run,omitempty"` }
type StepContext ¶
StepContext stores all the values accessible through the...
${{ step }}
...context in workflow files.
func (*StepContext) GetString ¶
func (c *StepContext) GetString(key string) string
GetString allows *StepContext to be accessed "like a map", e.g. *StepContext.GetString("outputs.digest") returns *StepContext.Outputs["digest"].
type Uses ¶
func Parse ¶
Parse parses a reference to a GitHub Action that would appear as the value of `uses` in a GitHub Actions Workflow Step, such as:
steps:
- uses: frantjc/forge@v1
- uses: ./
- uses: ./my/local/action
Also supports the special case ".".
func (*Uses) GetActionPath ¶
func (*Uses) GetRepository ¶
func (*Uses) MarshalJSON ¶
type WorkflowCommand ¶
func ParseWorkflowCommand ¶
func ParseWorkflowCommand(b []byte) (*WorkflowCommand, error)
ParseWorkflowCommand parses a workflow command from bytes. See ParseWorkflowCommandString for more details.
func ParseWorkflowCommandString ¶
func ParseWorkflowCommandString(workflowCommand string) (*WorkflowCommand, error)
ParseWorkflowCommandString parses a workflow command from a string such as:
::set-env name=HELLO::there
This supports a deprecated GitHub Actions function that used such strings written to stdout to send commands from a GitHub Action up to GitHub Actions.
func (*WorkflowCommand) GetName ¶
func (c *WorkflowCommand) GetName() string
GetName returns the value of the name parameter from the workflow command. Useful for set-env workflow commands as they require it to specify the name of the environment variable.
func (*WorkflowCommand) GoString ¶
func (c *WorkflowCommand) GoString() string
func (*WorkflowCommand) String ¶
func (c *WorkflowCommand) String() string
type WorkflowCommandWriter ¶ added in v0.13.8
type WorkflowCommandWriter struct { *GlobalContext ID string StopCommandsTokens map[string]bool Debug bool Masks []string Out io.Writer // contains filtered or unexported fields }
WorkflowCommandWriter holds the state of GitHub Actions workflow commands throughout the execution of a step.
func (*WorkflowCommandWriter) IssueCommand ¶ added in v0.13.8
func (w *WorkflowCommandWriter) IssueCommand(wc *WorkflowCommand) (int, error)