executor

type ActionsConfig struct {
	// Resolver is required to run actions from repositories; without it a job
	// that uses one fails "Set up job".
	Resolver Resolver
	// HTTPClient downloads the archives; nil means a client with the default
	// transport. It must not follow a redirect to another host with the
	// credentials (net/http does not).
	HTTPClient *http.Client
	// ExternalsDir is where Node.js lives (<dir>/node20/bin/node); empty means
	// /home/runner/externals.
	ExternalsDir string
	// DockerPath is the docker CLI; empty means the one found in PATH.
	DockerPath string
	// Node24ByDefault is the server flag actions.runner.usenode24bydefault
	// (HandlerFactory.cs, NodeUtil.DetermineActionsNodeVersion): ermite has no
	// feature flags, so the default is pinned here.
	Node24ByDefault bool
	// RequireNode24 is the server flag actions.runner.requirenode24 (phase 3
	// of the migration): every node20 action runs on node24 whatever
	// FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 and ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION
	// say, without the "being deprecated" notice or the conflict warning.
	// github.com does so today (recordings act-node-*). The zero value is the
	// runner's phase 1; the guest sets both flags (see DefaultActionsConfig).
	RequireNode24 bool
	// Containers are the time limits of the docker commands of job containers
	// and services; the zero value means the defaults.
	Containers ContainerTimeouts
	// Backoff, when set, replaces the random 10 to 30 s wait between download
	// attempts (tests).
	Backoff func() time.Duration
}

type Annotation struct {
	Level                AnnotationLevel
	Title, Message, File string
	StartLine, EndLine   int32
	StartColumn          int32
	EndColumn            int32
}

type AnnotationLevel string

type CancelReason int

type Canceller struct {
	// contains filtered or unexported fields
}

type Conclusion string

type Config struct {
	// WorkflowPath and WorkflowYAML are the workflow file, which the executor
	// parses itself; JobKey selects the job.
	WorkflowPath string
	WorkflowYAML []byte
	JobKey       string
	// JobName is the display name of the job, for "Complete job name: ...".
	// Empty means the job key.
	JobName string
	// ContextsJSON and MatrixJSON are the fields of the job message.
	ContextsJSON string
	MatrixJSON   string
	// Repo is the repository name used when the github context lacks one.
	Repo string
	// TimeoutMinutes is the job timeout; 0 means DefaultTimeoutMinutes. It is
	// used for the message and, without Deadline, for the timer.
	TimeoutMinutes int
	// Deadline is the time left of the job timeout when Run is called, when the
	// timeout started counting earlier (at the receipt of the job by the host);
	// 0 means TimeoutMinutes from now.
	Deadline time.Duration

	Runner        RunnerInfo
	RunnerVersion string
	// Layout overrides the directory layout (tests); nil means the hosted layout
	// under Home.
	Layout *Layout
	// Home is the home directory of the user of the steps; empty means
	// /home/runner.
	Home string
	// ToolCache is RUNNER_TOOL_CACHE; empty means DefaultToolCache. The official
	// runner reads it from its own environment (HostContext.cs:411).
	ToolCache string
	// BaseEnv is the environment steps inherit; nil means os.Environ().
	BaseEnv []string
	// CacheURL and CacheToken, when set, are ACTIONS_CACHE_URL and
	// ACTIONS_RUNTIME_TOKEN of the node and docker actions of the job: the cache
	// service of the runner. The token is masked in the log.
	CacheURL, CacheToken string
	// CacheMode is ACTIONS_CACHE_MODE ("read" or "write") next to the cache URL;
	// empty sets nothing.
	CacheMode string
	// ContainerCacheURL is CacheURL for the steps that run in a container (a
	// step in the job container, a docker action): the same relay on an address
	// of the sandbox their network reaches. Empty: those steps get no runtime
	// variables.
	ContainerCacheURL string
	// Results says that the service behind CacheURL also serves the results
	// service (artifacts) and that CacheToken carries its scope: node and docker
	// actions get ACTIONS_RESULTS_URL, and the node steps of the artifact actions
	// get a GITHUB_SERVER_URL @actions/artifact takes for GitHub (see
	// setArtifactsServerURL).
	Results bool
	// CacheOff says that the service behind CacheURL serves no cache (results
	// only): ACTIONS_CACHE_URL and ACTIONS_CACHE_MODE are not set.
	CacheOff bool
	// Secrets and Vars are Job.secrets and Job.vars. Secrets are registered in
	// the masker before the first step and form the secrets context; they are
	// never logged. Vars are the fallback of the vars context.
	Secrets, Vars map[string]string
	// SecretsWithheld says that the server did not send secrets because the run
	// is not trusted: "Set up job" says so.
	SecretsWithheld bool
	// TokenPermissions are the permissions of GITHUB_TOKEN as the server sent
	// them (Job.permissions: key to "read", "write" or "none"), which "Set up
	// job" prints as they are. Nil means the server sent none: they are then
	// worked out from the workflow. An empty, non-nil map is "none at all".
	TokenPermissions map[string]string
	// IDTokenURL and IDTokenRequestToken are Job.id_token_url (its origin
	// already rewritten for the sandbox) and Job.id_token_request_token:
	// ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN of the run
	// steps, node actions and docker actions (see addIDTokenEnv). Nothing is set
	// unless both are. The token is masked before anything is reported.
	IDTokenURL, IDTokenRequestToken string
	// Debug turns ##[debug] lines on (ACTIONS_STEP_DEBUG).
	Debug bool
	// Actions configures the actions of the job (resolution, downloads, Node.js,
	// docker).
	Actions ActionsConfig
	// SendAnnotations and SendSummaries say that the server keeps annotations
	// and step summaries (features ci.annotations and ci.summaries): the
	// Reporter then gets them with StepResults.
	SendAnnotations, SendSummaries bool
	// Getenv reads the environment of the executor (the matcher timeout); nil
	// means os.Getenv.
	Getenv func(string) string
	// StepTimeoutSkew is added to every step timeout (tests use a negative
	// value to run a timeout of one minute in milliseconds).
	StepTimeoutSkew time.Duration

	Reporter Reporter
	// Log receives the runner's own diagnostics (not the job log); the zero value
	// discards them.
	Log zerowrap.Logger

	// Credential, when set, is the user the steps run as.
	Credential *syscall.Credential
	// Cancellation timings and test hooks, see procSpec.
	TermAfter, KillAfter, WaitDelay time.Duration
	Signal                          func(pid int, sig syscall.Signal)
	// Now returns the current time; nil means time.Now.
	Now func() time.Time
}

type ContainerTimeouts struct {
	// Command bounds one docker command (default 2 minutes); Pull bounds a
	// docker pull (30 minutes).
	Command, Pull time.Duration
	// CleanupCommand bounds one command of "Stop containers" (30 seconds) and
	// CleanupBudget the whole cleanup (3 minutes), whatever happens to the job.
	CleanupCommand, CleanupBudget time.Duration
}

type FileCommands struct {
	// contains filtered or unexported fields
}

type Layout struct {
	Home string // HOME of the runner user
	// WorkRoot is the _work directory: <Home>/work.
	WorkRoot string
	// Temp is RUNNER_TEMP: <WorkRoot>/_temp.
	Temp string
	// ToolCache is RUNNER_TOOL_CACHE.
	ToolCache string
	// RunnerWorkspace is RUNNER_WORKSPACE: <WorkRoot>/<repo>.
	RunnerWorkspace string
	// Workspace is GITHUB_WORKSPACE: <WorkRoot>/<repo>/<repo>.
	Workspace string
	// Actions is where the actions of the job are downloaded: <WorkRoot>/_actions.
	Actions string
}

type Lookup struct {
	// Path is the PATH of the executor process (not of the step).
	Path string
	// Prepend is Global.PrependPath in the order of the AddPath calls.
	Prepend []string
}

type NotFoundError struct{ Command string }

type Pair struct{ Key, Value string }

type Reporter interface {
	// StepStarted announces a step that begins to run, with its display name.
	// A step skipped by its condition gets StepStarted and StepCompleted too.
	StepStarted(number int, name string, at time.Time)
	// Log is one line of the job log, without its line terminator.
	Log(number int, at time.Time, line string)
	// StepCompleted ends a step.
	StepCompleted(number int, name string, conclusion Conclusion, at time.Time)
	// JobCompleted is the last call: the result of the job.
	JobCompleted(Result)
}

type ResolvedAction struct {
	Ref, NameWithOwner, Path, ResolvedSHA, TarballURL, Token, Error string
	// AuthOrigin is the only origin (scheme://host[:port]) the Token is sent to;
	// the host sets it. Without it the token is not sent.
	AuthOrigin string
}

type Resolver func(ctx context.Context, uses []string) ([]ResolvedAction, error)

type Result struct {
	Conclusion Conclusion
	// Outputs are the job outputs, evaluated at the end of the job. Empty values
	// are left out, like the official runner does.
	Outputs map[string]string
	// Error is a job-level error (a timeout, a workflow that cannot be run);
	// step errors are in the log.
	Error string
	// RunnerShutdown is true when the job was cut short because the runner was
	// told to stop (see ErrShutdown).
	RunnerShutdown bool
}

type RunnerInfo struct {
	Name string
	// Environment is "self-hosted" (the default) or "github-hosted".
	Environment string
	// Arch is "X64" or "ARM64"; empty means the architecture of this process.
	Arch string
}

type Script struct {
	// Path is the script file.
	Path string
	// Argv is the command: the shell and its arguments with the script path.
	Argv []string
}

type ShellPlan struct {
	// Command is the shell command: "sh" for the default shell (whose path is
	// bash when found), else the first word of the shell option.
	Command string
	// CommandPath is the executable that is started, and shown on the
	// "shell:" line of the log.
	CommandPath string
	// ArgFormat is the argument format with {0} for the script path.
	ArgFormat string
}

type Sink interface {
	// SetEnv sets an environment variable of the job (GITHUB_ENV).
	SetEnv(name, value string)
	// SetOutput sets an output of the step (GITHUB_OUTPUT).
	SetOutput(name, value string)
	// AddPath prepends a directory to PATH for the next steps (GITHUB_PATH). The
	// caller keeps the list like Global.PrependPath: the last added is first
	// in PATH, and a repeated entry moves to the end of the list.
	AddPath(path string)
	// SaveState keeps a value for the step's own post phase (GITHUB_STATE).
	SaveState(name, value string)
	// Error writes an error issue to the log (##[error]).
	Error(msg string)
	// Debug writes a ##[debug] line when step debugging is on.
	Debug(msg string)
	// CommandFailed marks the step as failed (context.CommandResult = Failed).
	CommandFailed()
}

type State struct {
	// contains filtered or unexported fields
}

type StepResultReporter interface {
	StepResults(number int, r StepResults)
}

type StepResults struct {
	// Outcome is steps.<id>.outcome: the result before continue-on-error.
	Outcome Conclusion
	// Annotations is the whole list of the step, replacing any earlier one. It
	// is empty when ci.annotations is not available (Config.SendAnnotations).
	Annotations []Annotation
	// Summary is the masked GITHUB_STEP_SUMMARY of the step, HasSummary says
	// whether there is one. Empty when ci.summaries is not available
	// (Config.SendSummaries).
	Summary    string
	HasSummary bool
}