Documentation
¶
Overview ¶
Package actions defines the GitHub Actions workflow AST.
Workflow models native on, permissions, env, defaults, concurrency, and jobs properties. A Job either runs steps on RunsOn or calls a reusable workflow through Uses, With, and Secrets. Steps use Run or Uses and native If and Env properties. There are no platform-neutral envelopes or alternate CI targets.
Resolve validates output references and derives needs and job-output bindings without modifying the input. Lower builds a deterministic YAML value tree; Emit serializes it once. RawStep accepts authored GitHub Actions step mappings and rejects non-Actions properties.
Parse reads native workflow YAML and validates its dependency graph. Authored expression strings remain opaque; explicit needs are authoritative. AW Markdown source documents are modeled separately by the aw package. Parse followed by Emit round-trips the original YAML byte-for-byte, including comments, field order, quoting, and line endings. Resolve retains this source. After edits, Emit reconciles changes with the original syntax, preserving comments on retained nodes and moving step comments with their steps. Edited regions may be reformatted; aliases are materialized to preserve independent AST values. Lower remains a semantic tree without source comments.
Producers declare OutputDecl on a named step and write values to GITHUB_OUTPUT. Consumers use OutputRef in If, Env, With, or Secrets. Same-job references become steps.<id>.outputs.<name>; cross-job references expose a job output and add a needs edge. References with an empty Step name an explicit Job.Outputs entry or an output declared in a reusable-workflow caller's CallOutputs.
Step IDs are job-scoped. A step can only read outputs of earlier steps in its job, and job-level properties cannot read their own step outputs. Workflow env cannot reference job or step outputs.
Run contains a shell body, not YAML. Dynamic Actions values must pass through Env instead of being interpolated into scripts. Secret and Variable reference names, never resolved values. Or uses the Actions || truthiness rules.
Existing compiler generators contribute typed fields through workflow.Job.Actions. Existing steps run before typed steps, and their YAML comments and formatting are retained. The compiler resolves contributions after job augmentation and before rendering. Do not set a field in both its existing and typed form.
Index ¶
- func Emit(input *Workflow) (string, error)
- func Lower(input *Workflow) (yaml.MapSlice, error)
- func LowerStep(step Step, consumer JobID, resolved *Workflow) (map[string]any, error)
- func RenderExpression(expr Expression, consumer JobID, resolved *Workflow, wrap bool) (string, error)
- func ValidateJob(job *Job) error
- type ActionStep
- type Binary
- type Boolean
- type Call
- type Context
- type Expression
- type Job
- type JobID
- type Literal
- type Not
- type Number
- type OutputDecl
- type OutputName
- type OutputRef
- type RawStep
- type RunStep
- type SecretRef
- type Step
- type StepID
- type StepOptions
- type VariableRef
- type Workflow
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LowerStep ¶
LowerStep is also used by the compiler, retaining its existing field ordering, action-pin comments, and runner-specific rendering.
func RenderExpression ¶
func RenderExpression(expr Expression, consumer JobID, resolved *Workflow, wrap bool) (string, error)
RenderExpression lowers an expression in a resolved workflow. Call Resolve first so cross-job bindings and dependency validation have been completed.
func ValidateJob ¶
ValidateJob validates the runner or reusable-workflow shape of a job.
Types ¶
type ActionStep ¶
type ActionStep struct {
StepOptions
Uses string
With map[string]Expression
}
type Binary ¶
type Binary struct {
Left Expression
Operator string
Right Expression
}
type Call ¶
type Call struct {
Name string
Args []Expression
}
type Context ¶
type Context string
Context is the escape hatch for expressions not yet modeled by the AST. Its contents exclude the surrounding ${{ }} delimiters.
type Expression ¶
type Expression interface {
// contains filtered or unexported methods
}
Expression is shared by conditions, environment values, and action inputs. Environment values wrap everything except Literal in an Actions expression. Inputs also preserve Boolean and Number literals as native YAML scalars.
func Concat ¶
func Concat(values ...Expression) Expression
func Or ¶
func Or(value, fallback Expression) Expression
Or selects the fallback for falsy values using the Actions || operator.
func Secret ¶
func Secret(name string) Expression
func Variable ¶
func Variable(name string) Expression
type Job ¶
type Job struct {
ID JobID
Name string
RunsOn any
Needs []JobID
If Expression
Env map[string]Expression
Steps []Step
Outputs map[OutputName]Expression
Permissions any
Defaults map[string]any
Concurrency any
Environment any
Strategy map[string]any
Container any
Services map[string]any
TimeoutMinutes int
TimeoutMinutesExpression Expression
ContinueOnError Expression
// Uses makes this a reusable-workflow call rather than a runner job.
Uses string
With map[string]Expression
Secrets map[string]Expression
SecretsInherit bool
// CallOutputs declares outputs exported by the called workflow. These
// names are validated but are not emitted as caller-side output bindings.
CallOutputs []OutputDecl
}
type Not ¶
type Not struct{ Value Expression }
type OutputDecl ¶
type OutputDecl struct {
Name OutputName
}
type OutputName ¶
type OutputName string
type OutputRef ¶
type OutputRef struct {
Job JobID
Step StepID
Name OutputName
}
OutputRef identifies either a declared step output or, when Step is empty, an explicitly exposed job output.
type RawStep ¶
RawStep is one complete authored step mapping, without a list marker. The graph indexes its id, but cannot discover output declarations or typed references inside arbitrary scripts/expressions. Use typed steps for those.
type StepOptions ¶
type StepOptions struct {
ID StepID
Name string
If Expression
Env map[string]Expression
ContinueOnError Expression
TimeoutMinutes int
TimeoutMinutesExpression Expression
Outputs []OutputDecl
}
type VariableRef ¶
type VariableRef string
type Workflow ¶
type Workflow struct {
Name string
RunName string
On any
Permissions any
Env map[string]Expression
Defaults map[string]any
Concurrency any
Jobs []*Job
// contains filtered or unexported fields
}
Workflow contains only GitHub Actions workflow properties.
func Parse ¶
Parse builds and validates a native Actions graph from authored or generated YAML. Expressions in authored values remain opaque: their declared needs edges are authoritative, rather than inferred by scanning expression text. Emit retains the original source and its comments, including after AST edits.
Source Files