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

actioncontext

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package actioncontext provides the GitHub Actions runtime context of the current step.

Call Load to read it: it reads the default environment variables GitHub Actions sets for every step into an ActionContext, and decodes the event payload named by GITHUB_EVENT_NAME and GITHUB_EVENT_PATH into ActionContext.EventPayload, available through typed accessors such as ActionContext.PullRequestEvent. Importing the package has no side effects.

Variable reference: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActionContext 

type ActionContext struct {
	// GithubCI is always true on GitHub Actions. Environment variable: CI.
	GithubCI *bool `json:"githubCI,omitzero"`
	// Action is the name of the running action, or the id of a step. Environment variable: GITHUB_ACTION.
	Action string `json:"action,omitzero"`
	// ActionPath is the directory of the running action. Set only in composite actions. Environment variable: GITHUB_ACTION_PATH.
	ActionPath string `json:"actionPath,omitzero"`
	// ActionRepository is the owner and repository name of the running action. Environment variable: GITHUB_ACTION_REPOSITORY.
	ActionRepository string `json:"actionRepository,omitzero"`
	// Actions is true when GitHub Actions is running the workflow, which distinguishes a CI run from a local one. Environment variable: GITHUB_ACTIONS.
	Actions *bool `json:"actions,omitzero"`
	// Actor is the name of the person or app that initiated the workflow. Environment variable: GITHUB_ACTOR.
	Actor string `json:"actor,omitzero"`
	// ActorID is the account ID of the person or app that triggered the initial workflow run. Environment variable: GITHUB_ACTOR_ID.
	ActorID string `json:"actorId,omitzero"`
	// APIURL is the GitHub REST API base URL; [ActionContext.NewGitHubClient] targets it. Environment variable: GITHUB_API_URL.
	APIURL string `json:"apiUrl,omitzero"`
	// BaseRef is the target branch of the pull request. Set only for pull_request and pull_request_target. Environment variable: GITHUB_BASE_REF.
	BaseRef string `json:"baseRef,omitzero"`
	// EnvFilePath is the step's file for setting environment variables (see core.SetEnv). Environment variable: GITHUB_ENV.
	EnvFilePath string `json:"envFilePath,omitzero"`
	// EventName is the name of the event that triggered the workflow; it selects the type of [ActionContext.EventPayload]. Environment variable: GITHUB_EVENT_NAME.
	EventName string `json:"eventName,omitzero"`
	// EventPayloadFilePath is the file holding the event's full webhook payload. Environment variable: GITHUB_EVENT_PATH.
	EventPayloadFilePath string `json:"eventPayloadFilePath,omitzero"`
	// GraphQLURL is the GitHub GraphQL API URL. Environment variable: GITHUB_GRAPHQL_URL.
	GraphQLURL string `json:"graphqlUrl,omitzero"`
	// HeadRef is the source branch of the pull request. Set only for pull_request and pull_request_target. Environment variable: GITHUB_HEAD_REF.
	HeadRef string `json:"headRef,omitzero"`
	// JobID is the job_id of the current job. Environment variable: GITHUB_JOB.
	JobID string `json:"jobId,omitzero"`
	// OutputFilePath is the step's file for setting outputs (see core.SetOutput). Environment variable: GITHUB_OUTPUT.
	OutputFilePath string `json:"outputFilePath,omitzero"`
	// PathFilePath is the step's file for adding to PATH (see core.AddToPath). Environment variable: GITHUB_PATH.
	PathFilePath string `json:"pathFilePath,omitzero"`
	// Ref is the fully formed ref that triggered the run, e.g. refs/heads/main, refs/tags/v1.0.0 or refs/pull/45/merge. Environment variable: GITHUB_REF.
	Ref string `json:"ref,omitzero"`
	// RefName is the short name of the branch or tag that triggered the run. Environment variable: GITHUB_REF_NAME.
	RefName string `json:"refName,omitzero"`
	// RefProtected is true if branch protections or rulesets apply to the ref that triggered the run. Environment variable: GITHUB_REF_PROTECTED.
	RefProtected *bool `json:"refProtected,omitzero"`
	// RefType is the type of ref that triggered the run: branch or tag. Environment variable: GITHUB_REF_TYPE.
	RefType string `json:"refType,omitzero"`
	// Repository is the owner and repository name, e.g. octocat/Hello-World. Environment variable: GITHUB_REPOSITORY.
	Repository string `json:"repository,omitzero"`
	// RepositoryID is the ID of the repository. Environment variable: GITHUB_REPOSITORY_ID.
	RepositoryID string `json:"repositoryId,omitzero"`
	// RepositoryOwner is the repository owner's name. Environment variable: GITHUB_REPOSITORY_OWNER.
	RepositoryOwner string `json:"repositoryOwner,omitzero"`
	// RepositoryOwnerID is the repository owner's account ID. Environment variable: GITHUB_REPOSITORY_OWNER_ID.
	RepositoryOwnerID string `json:"repositoryOwnerId,omitzero"`
	// RetentionDays is how many days workflow run logs and artifacts are kept. Environment variable: GITHUB_RETENTION_DAYS.
	RetentionDays int `json:"retentionDays,omitzero"`
	// RunAttempt is the attempt number of this workflow run, starting at 1 and incremented on each re-run. Environment variable: GITHUB_RUN_ATTEMPT.
	RunAttempt int `json:"runAttempt,omitzero"`
	// RunID is the unique number of this workflow run within the repository; it does not change on re-runs. Environment variable: GITHUB_RUN_ID.
	RunID int `json:"runId,omitzero"`
	// RunNumber is the run's number within its workflow, starting at 1; it does not change on re-runs. Environment variable: GITHUB_RUN_NUMBER.
	RunNumber int `json:"runNumber,omitzero"`
	// ServerURL is the URL of the GitHub server, e.g. https://github.com. Environment variable: GITHUB_SERVER_URL.
	ServerURL string `json:"serverUrl,omitzero"`
	// Sha is the commit SHA that triggered the workflow; which commit depends on the event. Environment variable: GITHUB_SHA.
	Sha string `json:"sha,omitzero"`
	// StepSummaryFilePath is the step's job summary file (see core.StepSummary). Environment variable: GITHUB_STEP_SUMMARY.
	StepSummaryFilePath string `json:"stepSummaryFilePath,omitzero"`
	// TriggeringActor is the user that initiated the run; on a re-run it may differ from [ActionContext.Actor], whose privileges the run uses. Environment variable: GITHUB_TRIGGERING_ACTOR.
	TriggeringActor string `json:"triggeringActor,omitzero"`
	// Workflow is the name of the workflow. Environment variable: GITHUB_WORKFLOW.
	Workflow string `json:"workflow,omitzero"`
	// WorkflowRef is the ref path to the workflow file. Environment variable: GITHUB_WORKFLOW_REF.
	WorkflowRef string `json:"workflowRef,omitzero"`
	// WorkflowSha is the commit SHA of the workflow file. Environment variable: GITHUB_WORKFLOW_SHA.
	WorkflowSha string `json:"workflowSha,omitzero"`
	// WorkspacePath is the default working directory for steps and where actions/checkout puts the repository. Environment variable: GITHUB_WORKSPACE.
	WorkspacePath string `json:"workspacePath,omitzero"`
	// RunnerArch is the runner's architecture: X86, X64, ARM or ARM64. Environment variable: RUNNER_ARCH.
	RunnerArch string `json:"runnerArch,omitzero"`
	// RunnerDebug is true when debug logging is enabled; the variable is unset otherwise. Environment variable: RUNNER_DEBUG.
	RunnerDebug *bool `json:"runnerDebug,omitzero"`
	// RunnerEnvironment is github-hosted or self-hosted. Environment variable: RUNNER_ENVIRONMENT.
	RunnerEnvironment string `json:"runnerEnvironment,omitzero"`
	// RunnerName is the name of the runner executing the job; it may not be unique. Environment variable: RUNNER_NAME.
	RunnerName string `json:"runnerName,omitzero"`
	// RunnerOS is the runner's operating system: Linux, Windows or macOS. Environment variable: RUNNER_OS.
	RunnerOS string `json:"runnerOs,omitzero"`
	// RunnerTempPath is a temporary directory emptied at the start and end of each job. Environment variable: RUNNER_TEMP.
	RunnerTempPath string `json:"runnerTempPath,omitzero"`
	// RunnerToolCachePath is the directory of preinstalled tools on GitHub-hosted runners. Environment variable: RUNNER_TOOL_CACHE.
	RunnerToolCachePath string `json:"runnerToolCachePath,omitzero"`
	// EventPayload is the decoded event payload: a pointer to the github.com/google/go-github/v92/github event type matching [ActionContext.EventName], a *map[string]any for an event without a matching type, or nil when there is no event file. Prefer the typed accessors, such as [ActionContext.PullRequestEvent].
	EventPayload any `json:"eventPayload,omitzero"`
	// contains filtered or unexported fields
}

ActionContext is the GitHub Actions runtime context of the current step: the default environment variables and the decoded event payload. Use Load to populate one.

A string field is empty and a *bool field nil when its variable is unset; an int field is 0 when its variable is unset or not an integer.

func Load added in v0.2.0 

func Load() (*ActionContext, error)

Load reads the current step's context from the process environment and, when GITHUB_EVENT_NAME and GITHUB_EVENT_PATH are set, decodes the event payload file.

Load reads the environment and the file on every call; call it once and pass the result around. Outside GitHub Actions it returns a context with every field unset, not an error. It returns an error if the event file cannot be read or decoded.

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. GitHub sends comments on pull requests as issue_comment events too; check the payload's Issue.IsPullRequest to tell them apart.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.