model

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package model holds the workflow file model, its YAML parsing and the contexts that an expression reads. Gitea parses a workflow into it while planning a run, the runner while executing it.

Index

Constants

View Source 
const (
	// ActionRunsUsingNode12 for running with node12
	ActionRunsUsingNode12 = "node12"
	// ActionRunsUsingNode16 for running with node16
	ActionRunsUsingNode16 = "node16"
	// ActionRunsUsingNode20 for running with node20
	ActionRunsUsingNode20 = "node20"
	// ActionRunsUsingNode24 for running with node24
	ActionRunsUsingNode24 = "node24"
	// ActionRunsUsingDocker for running with docker
	ActionRunsUsingDocker = "docker"
	// ActionRunsUsingComposite for running composite
	ActionRunsUsingComposite = "composite"
	// ActionRunsUsingGo for running with go
	ActionRunsUsingGo = "go"
)
View Source 
const (
	StepStatusSuccess stepStatus = iota
	StepStatusFailure
	StepStatusSkipped
)

Variables

View Source 
var OnDecodeNodeError = func(node yaml.Node, out any, err error) {
	log.Fatalf("Failed to decode node %v into %T: %v", node, out, err)
}

Functions

func AsString 

func AsString(v any) string

AsString returns v as a string when it holds one, and "" otherwise.

func CloneYamlNode 

func CloneYamlNode(n yaml.Node) yaml.Node

CloneYamlNode returns a deep copy of a yaml.Node so callers can evaluate it in place without mutating a node shared across parallel jobs.

func NestedMapLookup 

func NestedMapLookup(m map[string]any, ks ...string) (rval any)

NestedMapLookup walks nested maps following the given keys and returns the value found at the end of the path, or nil if any key is missing.

func RunsOnFromNode 

func RunsOnFromNode(rawRunsOn yaml.Node) []string

RunsOnFromNode parses the runs-on labels from a raw runs-on node, so callers can evaluate a copy of the node (avoiding mutation of the shared Job) before reading the labels.

func UsesHash 

func UsesHash(uses string) string

UsesHash returns a hash of a `uses:` value. For Gitea.

Types

type Action 

type Action struct {
	Name        string            `yaml:"name"`
	Author      string            `yaml:"author"`
	Description string            `yaml:"description"`
	Inputs      map[string]Input  `yaml:"inputs"`
	Outputs     map[string]Output `yaml:"outputs"`
	Runs        ActionRuns        `yaml:"runs"`
	Branding    struct {
		Color string `yaml:"color"`
		Icon  string `yaml:"icon"`
	} `yaml:"branding"`
}

Action describes a metadata file for GitHub actions. The metadata filename must be either action.yml or action.yaml. The data in the metadata file defines the inputs, outputs and main entrypoint for your action.

func ReadAction 

func ReadAction(in io.Reader) (*Action, error)

ReadAction reads an action from a reader

type ActionRuns 

type ActionRuns struct {
	Using          ActionRunsUsing   `yaml:"using"`
	Env            map[string]string `yaml:"env"`
	Main           string            `yaml:"main"`
	Pre            string            `yaml:"pre"`
	PreIf          string            `yaml:"pre-if"`
	Post           string            `yaml:"post"`
	PostIf         string            `yaml:"post-if"`
	Image          string            `yaml:"image"`
	PreEntrypoint  string            `yaml:"pre-entrypoint"`
	Entrypoint     string            `yaml:"entrypoint"`
	PostEntrypoint string            `yaml:"post-entrypoint"`
	Args           []string          `yaml:"args"`
	Steps          []Step            `yaml:"steps"`
}

ActionRuns are a field in Action

type ActionRunsUsing 

type ActionRunsUsing string

ActionRunsUsing is the type of runner for the action

func (ActionRunsUsing) IsComposite 

func (a ActionRunsUsing) IsComposite() bool

func (ActionRunsUsing) IsDocker 

func (a ActionRunsUsing) IsDocker() bool

func (ActionRunsUsing) IsNode 

func (a ActionRunsUsing) IsNode() bool

func (*ActionRunsUsing) UnmarshalYAML 

func (a *ActionRunsUsing) UnmarshalYAML(unmarshal func(any) error) error

type ContainerSpec 

type ContainerSpec struct {
	Image       string            `yaml:"image"`
	Env         map[string]string `yaml:"env"`
	Ports       []string          `yaml:"ports"`
	Volumes     []string          `yaml:"volumes"`
	Options     string            `yaml:"options"`
	Credentials map[string]string `yaml:"credentials"`
	Entrypoint  string
	Args        string
	Name        string
	Reuse       bool

	// Gitea specific
	Cmd []string `yaml:"cmd"`
}

ContainerSpec is the specification of the container to use for the job

type Defaults 

type Defaults struct {
	Run RunDefaults `yaml:"run"`
}

Defaults are the settings that apply to all steps in the job or workflow

type GithubContext 

type GithubContext struct {
	Event            map[string]any `json:"event"`
	EventPath        string         `json:"event_path"`
	Workflow         string         `json:"workflow"`
	RunID            string         `json:"run_id"`
	RunNumber        string         `json:"run_number"`
	Actor            string         `json:"actor"`
	Repository       string         `json:"repository"`
	EventName        string         `json:"event_name"`
	Sha              string         `json:"sha"`
	Ref              string         `json:"ref"`
	RefName          string         `json:"ref_name"`
	RefType          string         `json:"ref_type"`
	HeadRef          string         `json:"head_ref"`
	BaseRef          string         `json:"base_ref"`
	Token            string         `json:"token"`
	Workspace        string         `json:"workspace"`
	Action           string         `json:"action"`
	ActionPath       string         `json:"action_path"`
	ActionRef        string         `json:"action_ref"`
	ActionRepository string         `json:"action_repository"`
	Job              string         `json:"job"`
	JobName          string         `json:"job_name"`
	RepositoryOwner  string         `json:"repository_owner"`
	RetentionDays    string         `json:"retention_days"`
	RunnerPerflog    string         `json:"runner_perflog"`
	RunnerTrackingID string         `json:"runner_tracking_id"`
	ServerURL        string         `json:"server_url"`
	APIURL           string         `json:"api_url"`
	GraphQLURL       string         `json:"graphql_url"`

	// For Gitea
	RunAttempt string `json:"run_attempt"`
}

func (*GithubContext) SetBaseAndHeadRef 

func (ghc *GithubContext) SetBaseAndHeadRef()

func (*GithubContext) SetRefTypeAndName 

func (ghc *GithubContext) SetRefTypeAndName()

type Input 

type Input struct {
	Description string `yaml:"description"`
	Required    bool   `yaml:"required"`
	Default     string `yaml:"default"`
}

Input parameters allow you to specify data that the action expects to use during runtime. GitHub stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids.

type Job 

type Job struct {
	Name               string                    `yaml:"name"`
	RawNeeds           yaml.Node                 `yaml:"needs"`
	RawRunsOn          yaml.Node                 `yaml:"runs-on"`
	Env                yaml.Node                 `yaml:"env"`
	If                 yaml.Node                 `yaml:"if"`
	Steps              []*Step                   `yaml:"steps"`
	TimeoutMinutes     string                    `yaml:"timeout-minutes"`
	RawContinueOnError string                    `yaml:"continue-on-error"`
	Services           map[string]*ContainerSpec `yaml:"services"`
	Strategy           *Strategy                 `yaml:"strategy"`
	RawContainer       yaml.Node                 `yaml:"container"`
	Defaults           Defaults                  `yaml:"defaults"`
	Outputs            map[string]string         `yaml:"outputs"`
	Uses               string                    `yaml:"uses"`
	With               map[string]any            `yaml:"with"`
	RawSecrets         yaml.Node                 `yaml:"secrets"`
	RawPermissions     yaml.Node                 `yaml:"permissions"`
	Result             string
	// Runtime fields set during execution (not from YAML):
	ContinueOnError bool // true when all failing matrix combinations had continue-on-error=true
	// contains filtered or unexported fields
}

Job is the structure of one job in a workflow

func (*Job) Container 

func (j *Job) Container() *ContainerSpec

Container details for the job

func (*Job) Environment 

func (j *Job) Environment() map[string]string

Environment returns string-based key=value map for a job

func (*Job) GetMatrixes 

func (j *Job) GetMatrixes() ([]map[string]any, error)

GetMatrixes returns the matrix cross product It skips includes and hard fails excludes for non-existing keys

func (*Job) InheritSecrets 

func (j *Job) InheritSecrets() bool

func (*Job) Matrix 

func (j *Job) Matrix() (map[string][]any, error)

Matrix decodes the RawMatrix YAML node into a map[string][]interface{}. Scalar values are wrapped into single-element arrays automatically. Template expressions are resolved by EvaluateYamlNode before this method is called; if unresolved, the literal string is wrapped as a one-element fallback.

func (*Job) Needs 

func (j *Job) Needs() []string

Needs list for Job

func (*Job) NeedsResult 

func (j *Job) NeedsResult() string

NeedsResult returns the job result as seen by dependent jobs through the `needs` context. A job that failed but was tolerated via continue-on-error reports "success" to its dependents, matching GitHub: such a failure must not block jobs gated on the default `if: success()`, even though the overall workflow run is still marked as failed.

func (*Job) RunsOn 

func (j *Job) RunsOn() []string

RunsOn list for Job

func (*Job) Secrets 

func (j *Job) Secrets() map[string]string

func (*Job) SetContinueOnError 

func (j *Job) SetContinueOnError(continueOnErr bool)

SetContinueOnError records whether this combination's failure should not fail the workflow. Must be called under the job lock. Safe across parallel matrix combinations.

func (*Job) Type 

func (j *Job) Type() (JobType, error)

Type returns the type of the job

type JobContainerContext 

type JobContainerContext struct {
	ID      string `json:"id"`
	Network string `json:"network"`
}

type JobContext 

type JobContext struct {
	Status    string                `json:"status"`
	Container JobContainerContext   `json:"container"`
	Services  map[string]JobService `json:"services"`
}

type JobService 

type JobService struct {
	ID      string            `json:"id"`
	Network string            `json:"network"`
	Ports   map[string]string `json:"ports"` // container port to the published host port
}

type JobType 

type JobType int

JobType describes what type of job we are about to run 

const (
	// JobTypeDefault is all jobs that have a `run` attribute
	JobTypeDefault JobType = iota

	// JobTypeReusableWorkflowLocal is all jobs that have a `uses` that is a local workflow in the .github/workflows directory
	JobTypeReusableWorkflowLocal

	// JobTypeReusableWorkflowRemote is all jobs that have a `uses` that references a workflow file in a github repo
	JobTypeReusableWorkflowRemote

	// JobTypeInvalid represents a job which is not configured correctly
	JobTypeInvalid
)

func (JobType) String 

func (j JobType) String() string

type Output 

type Output struct {
	Description string `yaml:"description"`
	Value       string `yaml:"value"`
}

Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions. For example, if you had an action that performed the addition of two inputs (x + y = z), the action could output the sum (z) for other actions to use as an input.

type Plan 

type Plan struct {
	Stages []*Stage
}

Plan contains a list of stages to run in series

func (*Plan) MaxRunNameLen 

func (p *Plan) MaxRunNameLen() int

MaxRunNameLen determines the max name length of all jobs

type RawConcurrency 

type RawConcurrency struct {
	Group            string `yaml:"group,omitempty"`
	CancelInProgress string `yaml:"cancel-in-progress,omitempty"`
	RawExpression    string `yaml:"-,omitempty"`
}

RawConcurrency represents a workflow concurrency or a job concurrency with uninterpolated options

func (*RawConcurrency) MarshalYAML 

func (r *RawConcurrency) MarshalYAML() (any, error)

func (*RawConcurrency) UnmarshalYAML 

func (r *RawConcurrency) UnmarshalYAML(n *yaml.Node) error

type Run 

type Run struct {
	Workflow *Workflow
	JobID    string
}

Run represents a job from a workflow that needs to be run

func (*Run) Job 

func (r *Run) Job() *Job

Job returns the job for this Run

func (*Run) String 

func (r *Run) String() string

type RunDefaults 

type RunDefaults struct {
	Shell            string `yaml:"shell"`
	WorkingDirectory string `yaml:"working-directory"`
}

RunDefaults are the settings that apply to all run steps in the job or workflow

type Stage 

type Stage struct {
	Runs []*Run
}

Stage contains a list of runs to execute in parallel

func (*Stage) GetJobIDs 

func (s *Stage) GetJobIDs() []string

GetJobIDs will get all the job names in the stage

type Step 

type Step struct {
	Number             int               `yaml:"-"`
	ID                 string            `yaml:"id"`
	If                 yaml.Node         `yaml:"if"`
	Name               string            `yaml:"name"`
	Uses               string            `yaml:"uses"`
	Run                string            `yaml:"run"`
	WorkingDirectory   string            `yaml:"working-directory"`
	Shell              string            `yaml:"shell"`
	Env                yaml.Node         `yaml:"env"`
	With               map[string]string `yaml:"with"`
	RawContinueOnError string            `yaml:"continue-on-error"`
	TimeoutMinutes     string            `yaml:"timeout-minutes"`
}

Step is the structure of one step in a job

func (*Step) Clone 

func (s *Step) Clone() *Step

Clone returns a deep copy safe to mutate independently of s. Job steps are shared across parallel matrix runs, which mutate per-job fields (ID, Number, Shell) and evaluate the If/Env yaml.Nodes in place, so each job must own its copy.

func (*Step) Environment 

func (s *Step) Environment() map[string]string

Environment returns string-based key=value map for a step

func (*Step) GetEnv 

func (s *Step) GetEnv() map[string]string

GetEnv gets the env for a step

func (*Step) ShellCommand 

func (s *Step) ShellCommand() string

ShellCommand returns the command for the shell

func (*Step) String 

func (s *Step) String() string

String gets the name of step

func (*Step) Type 

func (s *Step) Type() StepType

Type returns the type of the step

func (*Step) UsesHash 

func (s *Step) UsesHash() string

UsesHash returns a hash of the uses string. For Gitea.

type StepResult 

type StepResult struct {
	Outputs    map[string]string `json:"outputs"`
	Conclusion stepStatus        `json:"conclusion"`
	Outcome    stepStatus        `json:"outcome"`
}

type StepType 

type StepType int

StepType describes what type of step we are about to run 

const (
	// StepTypeRun is all steps that have a `run` attribute
	StepTypeRun StepType = iota

	// StepTypeUsesDockerURL is all steps that have a `uses` that is of the form `docker://...`
	StepTypeUsesDockerURL

	// StepTypeUsesActionLocal is all steps that have a `uses` that is a local action in a subdirectory
	StepTypeUsesActionLocal

	// StepTypeUsesActionRemote is all steps that have a `uses` that is a reference to a github repo
	StepTypeUsesActionRemote

	// StepTypeReusableWorkflowLocal is all steps that have a `uses` that is a local workflow in the .github/workflows directory
	StepTypeReusableWorkflowLocal

	// StepTypeReusableWorkflowRemote is all steps that have a `uses` that references a workflow file in a github repo
	StepTypeReusableWorkflowRemote

	// StepTypeInvalid is for steps that have invalid step action
	StepTypeInvalid
)

func (StepType) String 

func (s StepType) String() string

type Strategy 

type Strategy struct {
	FailFast          bool
	MaxParallel       int
	FailFastString    string    `yaml:"fail-fast"`
	MaxParallelString string    `yaml:"max-parallel"`
	RawMatrix         yaml.Node `yaml:"matrix"`
}

Strategy for the job

func (Strategy) GetFailFast 

func (s Strategy) GetFailFast() bool

GetFailFast sets default and returns value for `fail-fast`

func (Strategy) GetMaxParallel 

func (s Strategy) GetMaxParallel() int

GetMaxParallel sets default and returns value for `max-parallel`

type Workflow 

type Workflow struct {
	File           string
	Name           string            `yaml:"name"`
	RawOn          yaml.Node         `yaml:"on"`
	Env            map[string]string `yaml:"env"`
	Jobs           map[string]*Job   `yaml:"jobs"`
	Defaults       Defaults          `yaml:"defaults"`
	RawConcurrency *RawConcurrency   `yaml:"concurrency"`
	RawPermissions yaml.Node         `yaml:"permissions"`
}

Workflow is the structure of the files in .github/workflows

func ReadWorkflow 

func ReadWorkflow(in io.Reader) (*Workflow, error)

ReadWorkflow returns a list of jobs for a given workflow file reader

func (*Workflow) GetJob 

func (w *Workflow) GetJob(jobID string) *Job

GetJob will get a job by name in the workflow

func (*Workflow) GetJobIDs 

func (w *Workflow) GetJobIDs() []string

GetJobIDs will get all the job names in the workflow

func (*Workflow) On 

func (w *Workflow) On() []string

On events for the workflow

func (*Workflow) OnEvent 

func (w *Workflow) OnEvent(event string) any

func (*Workflow) OnSchedule 

func (w *Workflow) OnSchedule() []string

func (*Workflow) WorkflowCallConfig 

func (w *Workflow) WorkflowCallConfig() *WorkflowCall

func (*Workflow) WorkflowDispatchConfig 

func (w *Workflow) WorkflowDispatchConfig() *WorkflowDispatch

type WorkflowCall 

type WorkflowCall struct {
	Inputs  map[string]WorkflowCallInput  `yaml:"inputs"`
	Outputs map[string]WorkflowCallOutput `yaml:"outputs"`
}

type WorkflowCallInput 

type WorkflowCallInput struct {
	Description string `yaml:"description"`
	Required    bool   `yaml:"required"`
	Default     string `yaml:"default"`
	Type        string `yaml:"type"`
}

type WorkflowCallOutput 

type WorkflowCallOutput struct {
	Description string `yaml:"description"`
	Value       string `yaml:"value"`
}

type WorkflowCallResult 

type WorkflowCallResult struct {
	Outputs map[string]string
}

type WorkflowDispatch 

type WorkflowDispatch struct {
	Inputs map[string]WorkflowDispatchInput `yaml:"inputs"`
}

type WorkflowDispatchInput 

type WorkflowDispatchInput struct {
	Description string   `yaml:"description"`
	Required    bool     `yaml:"required"`
	Default     string   `yaml:"default"`
	Type        string   `yaml:"type"`
	Options     []string `yaml:"options"`
}

type WorkflowFiles 

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

type WorkflowPlanner 

type WorkflowPlanner interface {
	PlanEvent(eventName string) (*Plan, error)
	PlanJob(jobName string) (*Plan, error)
	PlanAll() (*Plan, error)
	GetEvents() []string
}

WorkflowPlanner contains methods for creating plans

func CombineWorkflowPlanner 

func CombineWorkflowPlanner(workflows ...*Workflow) WorkflowPlanner

CombineWorkflowPlanner combines workflows to a WorkflowPlanner

func NewSingleWorkflowPlanner 

func NewSingleWorkflowPlanner(name string, f io.Reader) (WorkflowPlanner, error)

func NewWorkflowPlanner 

func NewWorkflowPlanner(path string, noWorkflowRecurse bool) (WorkflowPlanner, error)

NewWorkflowPlanner will load a specific workflow, all workflows from a directory or all workflows from a directory and its subdirectories

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.