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

actioncontext

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: MIT Imports: 10 Imported by: 0

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

Examples

Constants

This section is empty.

Variables

View Source
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL