Documentation
¶
Overview ¶
Package actioncontext provides the GitHub Actions runtime context, auto-populated from environment variables at package import time.
The init function populates the package-level variables (such as Actor, Repository, and EventName) and CurrentActionContext by reading the standard GitHub Actions default environment variables.
The typed event payload in ActionContext.EventPayload and the per-type accessor methods (such as ActionContext.PullRequestEvent) are populated from the event file identified by GITHUB_EVENT_NAME and GITHUB_EVENT_PATH.
Example (PullRequest) ¶
Example_pullRequest demonstrates constructing a local ActionContext with a pull_request payload and using the typed PullRequestEvent accessor.
package main
import (
"fmt"
"github.com/google/go-github/v92/github"
"github.com/asteroid-computing/actions-toolkit-go/actioncontext"
)
func main() {
ac := &actioncontext.ActionContext{
EventName: "pull_request",
EventPayload: &github.PullRequestEvent{Number: new(42)},
}
pr, ok := ac.PullRequestEvent()
fmt.Println(pr.GetNumber(), ok)
}
Output: 42 true
Index ¶
- Variables
- type ActionContext
- func (ac *ActionContext) BranchProtectionRuleEvent() (*github.BranchProtectionRuleEvent, bool)
- func (ac *ActionContext) CheckRunEvent() (*github.CheckRunEvent, bool)
- func (ac *ActionContext) CheckSuiteEvent() (*github.CheckSuiteEvent, bool)
- func (ac *ActionContext) CreateEvent() (*github.CreateEvent, bool)
- func (ac *ActionContext) DeleteEvent() (*github.DeleteEvent, bool)
- func (ac *ActionContext) DeploymentEvent() (*github.DeploymentEvent, bool)
- func (ac *ActionContext) DeploymentStatusEvent() (*github.DeploymentStatusEvent, bool)
- func (ac *ActionContext) DiscussionCommentEvent() (*github.DiscussionCommentEvent, bool)
- func (ac *ActionContext) DiscussionEvent() (*github.DiscussionEvent, bool)
- func (ac *ActionContext) ForkEvent() (*github.ForkEvent, bool)
- func (ac *ActionContext) GollumEvent() (*github.GollumEvent, bool)
- func (ac *ActionContext) IssueCommentEvent() (*github.IssueCommentEvent, bool)
- func (ac *ActionContext) IssuesEvent() (*github.IssuesEvent, bool)
- func (ac *ActionContext) LabelEvent() (*github.LabelEvent, bool)
- func (ac *ActionContext) MergeGroupEvent() (*github.MergeGroupEvent, bool)
- func (ac *ActionContext) MilestoneEvent() (*github.MilestoneEvent, bool)
- func (ac *ActionContext) NewGitHubClient(opts ...github.ClientOptionsFunc) (*github.Client, error)
- func (ac *ActionContext) PackageEvent() (*github.PackageEvent, bool)
- func (ac *ActionContext) PageBuildEvent() (*github.PageBuildEvent, bool)
- func (ac *ActionContext) PublicEvent() (*github.PublicEvent, bool)
- func (ac *ActionContext) PullRequestEvent() (*github.PullRequestEvent, bool)
- func (ac *ActionContext) PullRequestReviewCommentEvent() (*github.PullRequestReviewCommentEvent, bool)
- func (ac *ActionContext) PullRequestReviewEvent() (*github.PullRequestReviewEvent, bool)
- func (ac *ActionContext) PullRequestTargetEvent() (*github.PullRequestTargetEvent, bool)
- func (ac *ActionContext) PushEvent() (*github.PushEvent, bool)
- func (ac *ActionContext) RawEventPayload() stdjson.RawMessage
- func (ac *ActionContext) RegistryPackageEvent() (*github.RegistryPackageEvent, bool)
- func (ac *ActionContext) ReleaseEvent() (*github.ReleaseEvent, bool)
- func (ac *ActionContext) RepositoryDispatchEvent() (*github.RepositoryDispatchEvent, bool)
- func (ac *ActionContext) RepositoryEvent() (*github.RepositoryEvent, bool)
- func (ac *ActionContext) StatusEvent() (*github.StatusEvent, bool)
- func (ac *ActionContext) String() string
- func (ac *ActionContext) WatchEvent() (*github.WatchEvent, bool)
- func (ac *ActionContext) WorkflowDispatchEvent() (*github.WorkflowDispatchEvent, bool)
- func (ac *ActionContext) WorkflowRunEvent() (*github.WorkflowRunEvent, bool)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // CurrentActionContext holds the populated [ActionContext] from GitHub Actions environment variables. CurrentActionContext *ActionContext // GithubCI indicates whether the runner is executing under GitHub Actions (CI). // During a GitHub Actions workflow run, this is always true. // Environment Variable: CI GithubCI *bool // Action is the name of the action currently running, or the id of a step. For example, for an action, __repo-owner_name-of-action-repo. // Environment Variable: GITHUB_ACTION Action string // ActionPath is the path where an action is located. This property is only supported in composite actions. // Environment Variable: GITHUB_ACTION_PATH ActionPath string // ActionRepository is, for a step executing an action, the owner and repository name of the action. // Environment Variable: GITHUB_ACTION_REPOSITORY ActionRepository string // Actions is always set to true when GitHub Actions is running the workflow. // You can use this variable to differentiate when tests are being run locally or by GitHub Actions. // Environment Variable: GITHUB_ACTIONS Actions *bool // Actor is the name of the person or app that initiated the workflow. // Environment Variable: GITHUB_ACTOR Actor string // ActorID is the account ID of the person or app that triggered the initial workflow run. // Environment Variable: GITHUB_ACTOR_ID ActorID string // APIURL is the GitHub REST API base URL // Environment Variable: GITHUB_API_URL APIURL string // BaseRef is the name of the base ref or target branch of the pull request in a workflow run. // This is only set when the event that triggers a workflow run is either pull_request or pull_request_target. // Environment Variable: GITHUB_BASE_REF BaseRef string // EnvFilePath is the path on the runner to the file that sets variables from workflow commands. // The path to this file is unique to the current step and changes for each step in a job. // Environment Variable: GITHUB_ENV EnvFilePath string // EventName is the name of the event that triggered the workflow. // Environment Variable: GITHUB_EVENT_NAME EventName string // EventPayloadFilePath is the path to the file on the runner that contains the full event webhook payload. // Environment Variable: GITHUB_EVENT_PATH EventPayloadFilePath string // GraphQLURL is the GitHub GraphQL API base URL. // Environment Variable: GITHUB_GRAPHQL_URL GraphQLURL string // HeadRef is the head ref or source branch of the pull request in a workflow run. // This property is only set when the event that triggers a workflow run is either pull_request or pull_request_target. // Environment Variable: GITHUB_HEAD_REF HeadRef string // JobID is the Job ID of the current job. // Environment Variable: GITHUB_JOB JobID string // OutputFilePath is the path on the runner to the file that sets the current step's outputs from workflow commands. // The path to this file is unique to the current step and changes for each step in a job. // Environment Variable: GITHUB_OUTPUT OutputFilePath string // PathFilePath is the path on the runner to the file that sets system PATH variables from workflow commands. // The path to this file is unique to the current step and changes for each step in a job. // Environment Variable: GITHUB_PATH PathFilePath string // Ref is the fully-formed ref of the branch or tag that triggered the workflow run. // For workflows triggered by push, this is the branch or tag ref that was pushed. // For workflows triggered by pull_request, this is the pull request merge branch. // For workflows triggered by release, this is the release tag created. // For other triggers, this is the branch or tag ref that triggered the workflow run. // This is only set if a branch or tag is available for the event type. // The ref given is fully-formed, meaning that for branches the format is refs/heads/<branch_name>. // For pull requests events except pull_request_target, it is refs/pull/<pr_number>/merge // pull_request_target events have the ref from the base branch. For tags it is refs/tags/<tag_name>. // Environment Variable: GITHUB_REF Ref string // RefName is the short ref name of the branch or tag that triggered the workflow run. // This value matches the branch or tag name shown on GitHub. // Environment Variable: GITHUB_REF_NAME RefName string // RefProtected is true if branch protections or rulesets are configured for the ref that triggered the workflow run. // Environment Variable: GITHUB_REF_PROTECTED RefProtected *bool // RefType is the type of ref that triggered the workflow run. Valid values are branch or tag. // Environment Variable: GITHUB_REF_TYPE RefType string // Repository is the owner and repository name. // Environment Variable: GITHUB_REPOSITORY Repository string // RepositoryID is the ID of the repository. // Environment Variable: GITHUB_REPOSITORY_ID RepositoryID string // RepositoryOwner is the repository owner's name. // Environment Variable: GITHUB_REPOSITORY_OWNER RepositoryOwner string // RepositoryOwnerID is the repository owner's account ID. // Environment Variable: GITHUB_REPOSITORY_OWNER_ID RepositoryOwnerID string // RetentionDays is the number of days that workflow run logs and artifacts are kept. // Environment Variable: GITHUB_RETENTION_DAYS RetentionDays int // RunAttempt is a unique number for each attempt of a particular workflow run in a repository. // This number begins at 1 for the workflow run's first attempt, and increments with each re-run. // Environment Variable: GITHUB_RUN_ATTEMPT RunAttempt int // RunID is a unique number for each workflow run within a repository. // This number does not change if you re-run the workflow run. // Environment Variable: GITHUB_RUN_ID RunID int // RunNumber is a unique number for each run of a particular workflow in a repository. // This number begins at 1 for the workflow's first run, and increments with each new run. // This number does not change if you re-run the workflow run. // Environment Variable: GITHUB_RUN_NUMBER RunNumber int // ServerURL is the URL of the GitHub server. // Environment Variable: GITHUB_SERVER_URL ServerURL string // Sha is the commit SHA that triggered the workflow. // The value of this commit SHA depends on the event that triggered the workflow. // Environment Variable: GITHUB_SHA Sha string // StepSummaryFilePath is the path on the runner to the file that contains job summaries from workflow commands. // The path to this file is unique to the current step and changes for each step in a job. // Environment Variable: GITHUB_STEP_SUMMARY StepSummaryFilePath string // TriggeringActor is the username of the user that initiated the workflow run. // If the workflow run is a re-run, this value may differ from github.actor. // Any workflow re-runs will use the privileges of github.actor, // even if the actor initiating the re-run (github.triggering_actor) has different privileges. // Environment Variable: GITHUB_TRIGGERING_ACTOR TriggeringActor string // Workflow is the name of the workflow. // Environment Variable: GITHUB_WORKFLOW Workflow string // WorkflowRef is the ref path to the workflow. // Environment Variable: GITHUB_WORKFLOW_REF WorkflowRef string // WorkflowSha is the commit SHA for the workflow file. // Environment Variable: GITHUB_WORKFLOW_SHA WorkflowSha string // WorkspacePath is the default working directory on the runner for steps, // and the default location of your repository when using the checkout action. // Environment Variable: GITHUB_WORKSPACE WorkspacePath string // RunnerArch is the architecture of the runner executing the job. Possible values are X86, X64, ARM, or ARM64. // Environment Variable: RUNNER_ARCH RunnerArch string // RunnerDebug is this is set only if debug logging is enabled, and always has the value of 1. // It can be useful as an indicator to enable additional debugging or verbose logging in your own job steps. // Environment Variable: RUNNER_DEBUG RunnerDebug *bool // RunnerEnvironment is the environment of the runner executing the job. // Possible values are: github-hosted for GitHub-hosted runners provided by GitHub, // and self-hosted for self-hosted runners configured by the repository owner. // Environment Variable: RUNNER_ENVIRONMENT RunnerEnvironment string // RunnerName is the name of the runner executing the job. // This name may not be unique in a workflow run as runners at the repository // and organization levels could use the same name. // Environment Variable: RUNNER_NAME RunnerName string // RunnerOS is the operating system of the runner executing the job. // Possible values are Linux, Windows, or macOS. // Environment Variable: RUNNER_OS RunnerOS string // RunnerTempPath is the path to a temporary directory on the runner. // This directory is emptied at the beginning and end of each job. // Note that files will not be removed if the runner's user account does not have permission to delete them. // Environment Variable: RUNNER_TEMP RunnerTempPath string // RunnerToolCachePath is the path to the directory containing preinstalled tools for GitHub-hosted runners. // Environment Variable: RUNNER_TOOL_CACHE RunnerToolCachePath string // EventPayload is the typed event payload object parsed from the event file. // The concrete type depends on [EventName] and is one of the // [github.com/google/go-github/v92/github] event types. EventPayload any )
The following exported variables are auto-populated at package import time from the GitHub Actions default environment variables. Each mirrors the same field on CurrentActionContext. Details for each variable: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables
Functions ¶
This section is empty.
Types ¶
type ActionContext ¶
type ActionContext struct {
GithubCI *bool `json:"githubCI,omitzero"`
Action string `json:"action,omitzero"`
ActionPath string `json:"actionPath,omitzero"`
ActionRepository string `json:"actionRepository,omitzero"`
Actions *bool `json:"actions,omitzero"`
Actor string `json:"actor,omitzero"`
ActorID string `json:"actorId,omitzero"`
APIURL string `json:"apiUrl,omitzero"`
BaseRef string `json:"baseRef,omitzero"`
EnvFilePath string `json:"envFilePath,omitzero"`
EventName string `json:"eventName,omitzero"`
EventPayloadFilePath string `json:"eventPayloadFilePath,omitzero"`
GraphQLURL string `json:"graphqlUrl,omitzero"`
HeadRef string `json:"headRef,omitzero"`
JobID string `json:"jobId,omitzero"`
OutputFilePath string `json:"outputFilePath,omitzero"`
PathFilePath string `json:"pathFilePath,omitzero"`
Ref string `json:"ref,omitzero"`
RefName string `json:"refName,omitzero"`
RefProtected *bool `json:"refProtected,omitzero"`
RefType string `json:"refType,omitzero"`
Repository string `json:"repository,omitzero"`
RepositoryID string `json:"repositoryId,omitzero"`
RepositoryOwner string `json:"repositoryOwner,omitzero"`
RepositoryOwnerID string `json:"repositoryOwnerId,omitzero"`
RetentionDays int `json:"retentionDays,omitzero"`
RunAttempt int `json:"runAttempt,omitzero"`
RunID int `json:"runId,omitzero"`
RunNumber int `json:"runNumber,omitzero"`
ServerURL string `json:"serverUrl,omitzero"`
Sha string `json:"sha,omitzero"`
StepSummaryFilePath string `json:"stepSummaryFilePath,omitzero"`
TriggeringActor string `json:"triggeringActor,omitzero"`
Workflow string `json:"workflow,omitzero"`
WorkflowRef string `json:"workflowRef,omitzero"`
WorkflowSha string `json:"workflowSha,omitzero"`
WorkspacePath string `json:"workspacePath,omitzero"`
RunnerArch string `json:"runnerArch,omitzero"`
RunnerDebug *bool `json:"runnerDebug,omitzero"`
RunnerEnvironment string `json:"runnerEnvironment,omitzero"`
RunnerName string `json:"runnerName,omitzero"`
RunnerOS string `json:"runnerOs,omitzero"`
RunnerTempPath string `json:"runnerTempPath,omitzero"`
RunnerToolCachePath string `json:"runnerToolCachePath,omitzero"`
EventPayload any `json:"eventPayload,omitzero"`
// contains filtered or unexported fields
}
ActionContext represents the complete GitHub Actions runtime context with all environment variables and event payload. Use CurrentActionContext for the auto-populated instance.
func (*ActionContext) BranchProtectionRuleEvent ¶
func (ac *ActionContext) BranchProtectionRuleEvent() (*github.BranchProtectionRuleEvent, bool)
BranchProtectionRuleEvent returns the event payload as a github.BranchProtectionRuleEvent and reports whether the current event is of that type.
func (*ActionContext) CheckRunEvent ¶
func (ac *ActionContext) CheckRunEvent() (*github.CheckRunEvent, bool)
CheckRunEvent returns the event payload as a github.CheckRunEvent and reports whether the current event is of that type.
func (*ActionContext) CheckSuiteEvent ¶
func (ac *ActionContext) CheckSuiteEvent() (*github.CheckSuiteEvent, bool)
CheckSuiteEvent returns the event payload as a github.CheckSuiteEvent and reports whether the current event is of that type.
func (*ActionContext) CreateEvent ¶
func (ac *ActionContext) CreateEvent() (*github.CreateEvent, bool)
CreateEvent returns the event payload as a github.CreateEvent and reports whether the current event is of that type.
func (*ActionContext) DeleteEvent ¶
func (ac *ActionContext) DeleteEvent() (*github.DeleteEvent, bool)
DeleteEvent returns the event payload as a github.DeleteEvent and reports whether the current event is of that type.
func (*ActionContext) DeploymentEvent ¶
func (ac *ActionContext) DeploymentEvent() (*github.DeploymentEvent, bool)
DeploymentEvent returns the event payload as a github.DeploymentEvent and reports whether the current event is of that type.
func (*ActionContext) DeploymentStatusEvent ¶
func (ac *ActionContext) DeploymentStatusEvent() (*github.DeploymentStatusEvent, bool)
DeploymentStatusEvent returns the event payload as a github.DeploymentStatusEvent and reports whether the current event is of that type.
func (*ActionContext) DiscussionCommentEvent ¶
func (ac *ActionContext) DiscussionCommentEvent() (*github.DiscussionCommentEvent, bool)
DiscussionCommentEvent returns the event payload as a github.DiscussionCommentEvent and reports whether the current event is of that type.
func (*ActionContext) DiscussionEvent ¶
func (ac *ActionContext) DiscussionEvent() (*github.DiscussionEvent, bool)
DiscussionEvent returns the event payload as a github.DiscussionEvent and reports whether the current event is of that type.
func (*ActionContext) ForkEvent ¶
func (ac *ActionContext) ForkEvent() (*github.ForkEvent, bool)
ForkEvent returns the event payload as a github.ForkEvent and reports whether the current event is of that type.
func (*ActionContext) GollumEvent ¶
func (ac *ActionContext) GollumEvent() (*github.GollumEvent, bool)
GollumEvent returns the event payload as a github.GollumEvent and reports whether the current event is of that type.
func (*ActionContext) IssueCommentEvent ¶
func (ac *ActionContext) IssueCommentEvent() (*github.IssueCommentEvent, bool)
IssueCommentEvent returns the event payload as a github.IssueCommentEvent and reports whether the current event is of that type. This accessor covers both the issue_comment and pull_request_comment event names, as both use the same payload type.
func (*ActionContext) IssuesEvent ¶
func (ac *ActionContext) IssuesEvent() (*github.IssuesEvent, bool)
IssuesEvent returns the event payload as a github.IssuesEvent and reports whether the current event is of that type.
func (*ActionContext) LabelEvent ¶
func (ac *ActionContext) LabelEvent() (*github.LabelEvent, bool)
LabelEvent returns the event payload as a github.LabelEvent and reports whether the current event is of that type.
func (*ActionContext) MergeGroupEvent ¶
func (ac *ActionContext) MergeGroupEvent() (*github.MergeGroupEvent, bool)
MergeGroupEvent returns the event payload as a github.MergeGroupEvent and reports whether the current event is of that type.
func (*ActionContext) MilestoneEvent ¶
func (ac *ActionContext) MilestoneEvent() (*github.MilestoneEvent, bool)
MilestoneEvent returns the event payload as a github.MilestoneEvent and reports whether the current event is of that type.
func (*ActionContext) NewGitHubClient ¶
func (ac *ActionContext) NewGitHubClient(opts ...github.ClientOptionsFunc) (*github.Client, error)
NewGitHubClient creates a github.Client targeting the API host derived from the context's APIURL field (sourced from GITHUB_API_URL).
When APIURL is empty or resolves to the public GitHub host (api.github.com), the client connects to the public API without any enterprise URL configuration.
When APIURL points to a GitHub Enterprise Server host, WithEnterpriseURLs is prepended to opts so the client targets the GHES instance. The upload URL is derived from the same scheme and host as APIURL.
Caller-supplied opts are applied after any derived enterprise option, so callers can override anything — including auth, timeout, or URLs. To authenticate, pass github.WithAuthToken.
func (*ActionContext) PackageEvent ¶
func (ac *ActionContext) PackageEvent() (*github.PackageEvent, bool)
PackageEvent returns the event payload as a github.PackageEvent and reports whether the current event is of that type.
func (*ActionContext) PageBuildEvent ¶
func (ac *ActionContext) PageBuildEvent() (*github.PageBuildEvent, bool)
PageBuildEvent returns the event payload as a github.PageBuildEvent and reports whether the current event is of that type.
func (*ActionContext) PublicEvent ¶
func (ac *ActionContext) PublicEvent() (*github.PublicEvent, bool)
PublicEvent returns the event payload as a github.PublicEvent and reports whether the current event is of that type.
func (*ActionContext) PullRequestEvent ¶
func (ac *ActionContext) PullRequestEvent() (*github.PullRequestEvent, bool)
PullRequestEvent returns the event payload as a github.PullRequestEvent and reports whether the current event is of that type.
func (*ActionContext) PullRequestReviewCommentEvent ¶
func (ac *ActionContext) PullRequestReviewCommentEvent() (*github.PullRequestReviewCommentEvent, bool)
PullRequestReviewCommentEvent returns the event payload as a github.PullRequestReviewCommentEvent and reports whether the current event is of that type.
func (*ActionContext) PullRequestReviewEvent ¶
func (ac *ActionContext) PullRequestReviewEvent() (*github.PullRequestReviewEvent, bool)
PullRequestReviewEvent returns the event payload as a github.PullRequestReviewEvent and reports whether the current event is of that type.
func (*ActionContext) PullRequestTargetEvent ¶
func (ac *ActionContext) PullRequestTargetEvent() (*github.PullRequestTargetEvent, bool)
PullRequestTargetEvent returns the event payload as a github.PullRequestTargetEvent and reports whether the current event is of that type.
func (*ActionContext) PushEvent ¶
func (ac *ActionContext) PushEvent() (*github.PushEvent, bool)
PushEvent returns the event payload as a github.PushEvent and reports whether the current event is of that type.
func (*ActionContext) RawEventPayload ¶
func (ac *ActionContext) RawEventPayload() stdjson.RawMessage
RawEventPayload returns the unparsed JSON bytes of the event payload read from the event file. It returns nil if no event file was loaded. This escape hatch lets consumers on a different go-github major version — or any package that needs fields not covered by the typed accessors — unmarshal the raw JSON themselves.
func (*ActionContext) RegistryPackageEvent ¶
func (ac *ActionContext) RegistryPackageEvent() (*github.RegistryPackageEvent, bool)
RegistryPackageEvent returns the event payload as a github.RegistryPackageEvent and reports whether the current event is of that type.
func (*ActionContext) ReleaseEvent ¶
func (ac *ActionContext) ReleaseEvent() (*github.ReleaseEvent, bool)
ReleaseEvent returns the event payload as a github.ReleaseEvent and reports whether the current event is of that type.
func (*ActionContext) RepositoryDispatchEvent ¶
func (ac *ActionContext) RepositoryDispatchEvent() (*github.RepositoryDispatchEvent, bool)
RepositoryDispatchEvent returns the event payload as a github.RepositoryDispatchEvent and reports whether the current event is of that type.
func (*ActionContext) RepositoryEvent ¶
func (ac *ActionContext) RepositoryEvent() (*github.RepositoryEvent, bool)
RepositoryEvent returns the event payload as a github.RepositoryEvent and reports whether the current event is of that type.
func (*ActionContext) StatusEvent ¶
func (ac *ActionContext) StatusEvent() (*github.StatusEvent, bool)
StatusEvent returns the event payload as a github.StatusEvent and reports whether the current event is of that type.
func (*ActionContext) String ¶
func (ac *ActionContext) String() string
String returns a pretty-printed representation of the ActionContext with all fields. String fields that are zero-valued are shown as empty, bool pointer fields that are nil are shown as "<nil>".
func (*ActionContext) WatchEvent ¶
func (ac *ActionContext) WatchEvent() (*github.WatchEvent, bool)
WatchEvent returns the event payload as a github.WatchEvent and reports whether the current event is of that type.
func (*ActionContext) WorkflowDispatchEvent ¶
func (ac *ActionContext) WorkflowDispatchEvent() (*github.WorkflowDispatchEvent, bool)
WorkflowDispatchEvent returns the event payload as a github.WorkflowDispatchEvent and reports whether the current event is of that type.
func (*ActionContext) WorkflowRunEvent ¶
func (ac *ActionContext) WorkflowRunEvent() (*github.WorkflowRunEvent, bool)
WorkflowRunEvent returns the event payload as a github.WorkflowRunEvent and reports whether the current event is of that type.