validate_actions.domain_model.ast¶

Abstract Syntax Tree (AST) models for GitHub Actions workflows.

This module defines the domain model for GitHub Actions workflows, providing a structured representation of workflow files that enables validation, analysis, and manipulation. The AST nodes preserve position information for accurate error reporting and auto-fixing.

The AST hierarchy mirrors GitHub Actions workflow structure: - Workflow (root) -> Jobs -> Steps -> Actions/Commands - Events define workflow triggers - Contexts provide runtime data access - Permissions control repository access

All AST nodes use PyYAML token-level parsing to maintain precise position tracking.

Classes

`ActionMetadata`([required_inputs, ...])	Metadata about a GitHub Action for validation.
`BranchesFilterEvent`(*, id[, types_, ...])	Event with branch filtering capabilities.
`Concurrency`(pos, group_[, cancel_in_progress_])	Workflow concurrency control configuration.
`Container`(pos, image_[, credentials_, env_, ...])	Container configuration for job execution.
`ContainerCredentials`(pos, username_, password_)	Authentication credentials for private container registries.
`Defaults`(pos[, shell_, working_directory_])	Default settings for run steps.
`Env`(variables)	Environment variables container with convenient access methods.
`Environment`(pos, name_[, url_])	Deployment environment configuration.
`Event`(*, id[, types_])	Base class for all workflow trigger events.
`Exec`()	Abstract base class for step execution types.
`ExecAction`(pos, uses_, with_[, metadata, ...])	Step that executes a GitHub Action.
`ExecRun`(pos, run_[, shell_, working_directory_])	Step that executes shell commands.
`Job`(pos, job_id_, steps_, contexts[, name_, ...])	Individual job within a workflow.
`PathsBranchesFilterEvent`([paths_, ...])	Event with branch and path filtering.
`Permission`(*values)	GitHub repository permission levels.
`Permissions`([actions_, attestations_, ...])	Repository permissions configuration for GITHUB_TOKEN.
`RunsOn`(pos[, labels, group])	Runner selection configuration for jobs.
`ScheduleEvent`(cron_, *, id[, types_])	Scheduled workflow trigger using cron syntax.
`Secrets`(pos[, inherit, secrets])	Secret configuration for reusable workflow calls.
`Shell`(*values)	Supported shell types for run steps.
`Step`(pos, exec, contexts[, id_, if_, name_, ...])	Individual step within a job.
`Strategy`(pos, combinations, fail_fast_, ...)	Job execution strategy with matrix and parallelism controls.
`TagsPathsBranchesFilterEvent`([paths_, ...])	Event with comprehensive filtering options.
`Workflow`(on_, jobs_, contexts[, name_, ...])	Root AST node representing a complete GitHub Actions workflow.
`WorkflowCallEvent`([inputs_, outputs_, ...])	Event for reusable workflow calls.
`WorkflowCallEventInput`(id[, description_, ...])	Typed input parameter for reusable workflows.
`WorkflowCallEventOutput`(id, value_[, ...])	Output value definition for reusable workflows.
`WorkflowCallEventSecret`(id[, description_, ...])	Secret parameter for reusable workflows.
`WorkflowCallInputType`(*values)	Supported input types for reusable workflow calls.
`WorkflowDispatchEvent`([inputs_, types_])	Manual workflow trigger with optional inputs.
`WorkflowDispatchEventInput`(id[, ...])	User input for manual workflow dispatch.
`WorkflowDispatchInputType`(*values)	Supported input types for manual workflow dispatch.
`WorkflowInput`(id[, description_, default_, ...])	Base class for workflow input parameters.
`WorkflowRunEvent`(*, id[, types_, branches_, ...])	Event triggered by other workflow completions.

class validate_actions.domain_model.ast.Workflow(on_, jobs_, contexts, name_=None, run_name_=None, permissions_=<factory>, env_=None, defaults_=None, concurrency_=None)[source]¶

Bases: object

Root AST node representing a complete GitHub Actions workflow.

Contains all workflow-level configuration including events, jobs, and global settings. Each workflow maintains its own context scope for expression validation.

Parameters:

on_ (List[Event])
jobs_ (Dict[String, Job])
contexts (Contexts)
name_ (str | None)
run_name_ (str | None)
permissions_ (Permissions)
env_ (Env | None)
defaults_ (Defaults | None)
concurrency_ (Concurrency | None)

on_¶

List of events that trigger this workflow

Type:: List[Event]

jobs_¶

Dictionary mapping job IDs to Job objects

Type:: Dict[String, Job]

contexts¶

Available GitHub Actions contexts for expression validation

Type:: Contexts

name_¶

Optional display name for the workflow

Type:: str | None

run_name_¶

Optional dynamic run name expression

Type:: str | None

permissions_¶

Repository permissions for GITHUB_TOKEN

Type:: Permissions

env_¶

Global environment variables

Type:: Env | None

defaults_¶

Default shell and working directory settings

Type:: Defaults | None

concurrency_¶

Workflow concurrency controls

Type:: Concurrency | None

class validate_actions.domain_model.ast.Permission(*values)[source]¶

Bases: Enum

GitHub repository permission levels.

Defines the access level granted to the GITHUB_TOKEN for repository operations.

class validate_actions.domain_model.ast.Permissions(actions_=Permission(), attestations_=Permission(), checks_=Permission(), contents_=Permission(), deployments_=Permission(), id_token_=Permission(), issues_=Permission(), metadata_=Permission(), models_=Permission(), discussions_=Permission(), packages_=Permission(), pages_=Permission(), pull_requests_=Permission(), security_events_=Permission(), statuses_=Permission())[source]¶

Bases: object

Repository permissions configuration for GITHUB_TOKEN.

Defines fine-grained permissions for different repository scopes. Default values are permissive to match GitHub’s behavior.

Parameters:

actions_ (Permission)
attestations_ (Permission)
checks_ (Permission)
contents_ (Permission)
deployments_ (Permission)
id_token_ (Permission)
issues_ (Permission)
metadata_ (Permission)
models_ (Permission)
discussions_ (Permission)
packages_ (Permission)
pages_ (Permission)
pull_requests_ (Permission)
security_events_ (Permission)
statuses_ (Permission)

actions_¶

Permissions for GitHub Actions

Type:: Permission

attestations_¶

Permissions for attestations

Type:: Permission

checks_¶

Permissions for checks API

Type:: Permission

contents_¶

Permissions for repository contents

Type:: Permission

deployments_¶

Permissions for deployments

Type:: Permission

id_token_¶

Permissions for ID token generation

Type:: Permission

issues_¶

Permissions for issues API

Type:: Permission

metadata_¶

Permissions for repository metadata

Type:: Permission

models_¶

Permissions for repository models (e.g. code scanning)

Type:: Permission

discussions_¶

Permissions for discussions API

Type:: Permission

packages_¶

Permissions for package registry

Type:: Permission

pages_¶

Permissions for GitHub Pages

Type:: Permission

pull_requests_¶

Permissions for pull requests API

Type:: Permission

security_events_¶

Permissions for security events

Type:: Permission

statuses_¶

Permissions for commit statuses

Type:: Permission

class validate_actions.domain_model.ast.Shell(*values)[source]¶

Bases: Enum

Supported shell types for run steps.

Maps to GitHub Actions runner shell options.

class validate_actions.domain_model.ast.Defaults(pos, shell_=None, working_directory_=None)[source]¶

Bases: object

Default settings for run steps.

Provides workflow-level defaults that can be overridden at job or step level.

Parameters:

pos (Pos)
shell_ (Shell | None)
working_directory_ (String | None)

pos¶

Position in source file for error reporting

Type:: Pos

shell_¶

Default shell for run steps

Type:: Shell | None

working_directory_¶

Default working directory for run steps

Type:: String | None

class validate_actions.domain_model.ast.Env(variables)[source]¶

Bases: object

Environment variables container with convenient access methods.

Stores environment variables as String objects to preserve position information. Provides dict-like access for easy variable lookup.

Parameters:: variables (Dict[String, String])

variables¶

Dictionary mapping variable names to values

Type:: Dict[String, String]

get(key)[source]¶

Gets a variable value by key string if it exists.

Parameters:: key (str)
Return type:: String | None

class validate_actions.domain_model.ast.Concurrency(pos, group_, cancel_in_progress_=None)[source]¶

Bases: object

Workflow concurrency control configuration.

Manages concurrent execution of workflow runs to prevent conflicts.

Parameters:

pos (Pos)
group_ (String)
cancel_in_progress_ (bool | String | None)

pos¶

Position in source file for error reporting

Type:: Pos

group_¶

Concurrency group identifier (can be expression)

Type:: String

cancel_in_progress_¶

Whether to cancel in-progress runs when new run starts

Type:: bool | String | None

class validate_actions.domain_model.ast.Event(*, id, types_=None)[source]¶

Bases: object

Base class for all workflow trigger events.

Events define when workflows should execute. Each event type supports different configuration options and filtering capabilities.

Parameters:

id (String)
types_ (List[String] | None)

id¶

Event name (push, pull_request, schedule, etc.)

Type:: String

types_¶

Optional list of event subtypes to filter on

Type:: List[String] | None

class validate_actions.domain_model.ast.BranchesFilterEvent(*, id, types_=None, branches_=None, branches_ignore_=None)[source]¶

Bases: Event

Event with branch filtering capabilities.

Base for events that can be filtered by branch names using glob patterns.

Parameters:

id (String)
types_ (List[String] | None)
branches_ (List[String] | None)
branches_ignore_ (List[String] | None)

branches_¶

List of branch patterns to include

Type:: List[String] | None

branches_ignore_¶

List of branch patterns to exclude

Type:: List[String] | None

class validate_actions.domain_model.ast.PathsBranchesFilterEvent(paths_=None, paths_ignore_=None, *, id, types_=None, branches_=None, branches_ignore_=None)[source]¶

Bases: BranchesFilterEvent

Event with branch and path filtering.

Extends branch filtering with file path pattern matching.

Parameters:

paths_ (List[String] | None)
paths_ignore_ (List[String] | None)
id (String)
types_ (List[String] | None)
branches_ (List[String] | None)
branches_ignore_ (List[String] | None)

paths_¶

List of file path patterns to include

Type:: List[String] | None

paths_ignore_¶

List of file path patterns to exclude

Type:: List[String] | None

class validate_actions.domain_model.ast.TagsPathsBranchesFilterEvent(paths_=None, paths_ignore_=None, tags_=None, tags_ignore_=None, *, id, types_=None, branches_=None, branches_ignore_=None)[source]¶

Bases: PathsBranchesFilterEvent

Event with comprehensive filtering options.

Supports filtering by branches, paths, and git tags.

Parameters:

paths_ (List[String] | None)
paths_ignore_ (List[String] | None)
tags_ (List[String] | None)
tags_ignore_ (List[String] | None)
id (String)
types_ (List[String] | None)
branches_ (List[String] | None)
branches_ignore_ (List[String] | None)

tags_¶

List of tag patterns to include

Type:: List[String] | None

tags_ignore_¶

List of tag patterns to exclude

Type:: List[String] | None

class validate_actions.domain_model.ast.ScheduleEvent(cron_, *, id, types_=None)[source]¶

Bases: Event

Scheduled workflow trigger using cron syntax.

Enables time-based workflow execution with cron expressions.

Parameters:

cron_ (List[String])
id (String)
types_ (List[String] | None)

cron_¶

List of cron expressions defining schedule

Type:: List[String]

class validate_actions.domain_model.ast.WorkflowInput(id, description_=None, default_=None, required_=False)[source]¶

Bases: ABC

Base class for workflow input parameters.

Defines common properties for inputs to reusable workflows.

Parameters:

id (String)
description_ (String | None)
default_ (String | None)
required_ (bool)

id¶

Input parameter name

Type:: String

description_¶

Human-readable description

Type:: String | None

default_¶

Default value if not provided

Type:: String | None

required_¶

Whether input is mandatory

Type:: bool

class validate_actions.domain_model.ast.WorkflowCallEvent(inputs_=None, outputs_=None, secrets_=None, *, id, types_=None)[source]¶

Bases: Event

Event for reusable workflow calls.

Defines interface for workflows that can be called by other workflows.

Parameters:

inputs_ (List[WorkflowCallEventInput] | None)
outputs_ (List[WorkflowCallEventOutput] | None)
secrets_ (List[WorkflowCallEventSecret] | None)
id (String)
types_ (List[String] | None)

inputs_¶

Input parameters accepted by this workflow

Type:: List[WorkflowCallEventInput] | None

outputs_¶

Output values provided by this workflow

Type:: List[WorkflowCallEventOutput] | None

secrets_¶

Secret parameters required by this workflow

Type:: List[WorkflowCallEventSecret] | None

class validate_actions.domain_model.ast.WorkflowCallInputType(*values)[source]¶

Bases: Enum

Supported input types for reusable workflow calls.

class validate_actions.domain_model.ast.WorkflowCallEventInput(id, description_=None, default_=None, required_=False, *, type_)[source]¶

Bases: WorkflowInput

Typed input parameter for reusable workflows.

Parameters:

id (String)
description_ (String | None)
default_ (String | None)
required_ (bool)
type_ (WorkflowCallInputType)

type_¶

Data type constraint for the input value

Type:: WorkflowCallInputType

class validate_actions.domain_model.ast.WorkflowCallEventOutput(id, value_, description_=None)[source]¶

Bases: object

Output value definition for reusable workflows.

Parameters:

id (String)
value_ (String)
description_ (String | None)

id¶

Output name

Type:: String

value_¶

Expression that computes the output value

Type:: String

description_¶

Human-readable description

Type:: String | None

class validate_actions.domain_model.ast.WorkflowCallEventSecret(id, description_=None, required_=False)[source]¶

Bases: object

Secret parameter for reusable workflows.

Parameters:

id (String)
description_ (String | None)
required_ (bool)

id¶

Secret name

Type:: String

description_¶

Human-readable description

Type:: String | None

required_¶

Whether secret must be provided

Type:: bool

class validate_actions.domain_model.ast.WorkflowRunEvent(*, id, types_=None, branches_=None, branches_ignore_=None, workflows_)[source]¶

Bases: BranchesFilterEvent

Event triggered by other workflow completions.

Parameters:

id (String)
types_ (List[String] | None)
branches_ (List[String] | None)
branches_ignore_ (List[String] | None)
workflows_ (List[String])

workflows_¶

List of workflow names that trigger this event

Type:: List[String]

class validate_actions.domain_model.ast.WorkflowDispatchEvent(inputs_=None, *, id, types_=None)[source]¶

Bases: Event

Manual workflow trigger with optional inputs.

Enables manual workflow execution through GitHub UI or API.

Parameters:

inputs_ (List[WorkflowDispatchEventInput] | None)
id (String)
types_ (List[String] | None)

inputs_¶

User-configurable input parameters

Type:: List[WorkflowDispatchEventInput] | None

class validate_actions.domain_model.ast.WorkflowDispatchInputType(*values)[source]¶

Bases: Enum

Supported input types for manual workflow dispatch.

class validate_actions.domain_model.ast.WorkflowDispatchEventInput(id, description_=None, default_=None, required_=False, *, type_, options_=None)[source]¶

Bases: WorkflowInput

User input for manual workflow dispatch.

Parameters:

id (String)
description_ (String | None)
default_ (String | None)
required_ (bool)
type_ (WorkflowDispatchInputType)
options_ (List[String] | None)

type_¶

Input type determining UI widget

Type:: WorkflowDispatchInputType

options_¶

Available choices for ‘choice’ type inputs

Type:: List[String] | None

class validate_actions.domain_model.ast.RunsOn(pos, labels=<factory>, group=<factory>)[source]¶

Bases: object

Runner selection configuration for jobs.

Specifies which GitHub Actions runners should execute the job. Supports both individual labels and runner groups.

Parameters:

pos (Pos)
labels (List[String])
group (List[String])

pos¶

Position in source file for error reporting

Type:: Pos

labels¶

Individual runner labels (ubuntu-latest, windows-2022, etc.)

Type:: List[String]

group¶

Runner group names for organization-level runner pools

Type:: List[String]

class validate_actions.domain_model.ast.Strategy(pos, combinations, fail_fast_, max_parallel_)[source]¶

Bases: object

Job execution strategy with matrix and parallelism controls.

Defines how jobs should be executed across different configurations.

Parameters:

pos (Pos)
combinations (List[Dict[String, String]])
fail_fast_ (bool | None)
max_parallel_ (int | None)

pos¶

Position in source file for error reporting

Type:: Pos

combinations¶

Matrix of variable combinations to execute

Type:: List[Dict[String, String]]

fail_fast_¶

Whether to cancel remaining jobs on first failure

Type:: bool | None

max_parallel_¶

Maximum number of concurrent job instances

Type:: int | None

class validate_actions.domain_model.ast.Environment(pos, name_, url_=None)[source]¶

Bases: object

Deployment environment configuration.

Links jobs to GitHub deployment environments for additional controls.

Parameters:

pos (Pos)
name_ (String)
url_ (String | None)

pos¶

Position in source file for error reporting

Type:: Pos

name_¶

Environment name

Type:: String

url_¶

Optional environment URL for deployments

Type:: String | None

class validate_actions.domain_model.ast.ContainerCredentials(pos, username_, password_)[source]¶

Bases: object

Authentication credentials for private container registries.

Parameters:

pos (Pos)
username_ (String)
password_ (String)

pos¶

Position in source file for error reporting

Type:: Pos

username_¶

Registry username

Type:: String

password_¶

Registry password or token

Type:: String

class validate_actions.domain_model.ast.Container(pos, image_, credentials_=None, env_=None, ports_=None, volumes_=None, options_=None)[source]¶

Bases: object

Container configuration for job execution.

Enables running jobs inside Docker containers for consistent environments.

Parameters:

pos (Pos)
image_ (String)
credentials_ (ContainerCredentials | None)
env_ (Env | None)
ports_ (List[String] | None)
volumes_ (List[String] | None)
options_ (String | None)

pos¶

Position in source file for error reporting

Type:: Pos

image_¶

Container image reference

Type:: String

credentials_¶

Optional registry authentication

Type:: ContainerCredentials | None

env_¶

Container environment variables

Type:: Env | None

ports_¶

Port mappings between host and container

Type:: List[String] | None

volumes_¶

Volume mounts for persistent storage

Type:: List[String] | None

options_¶

Additional Docker run options

Type:: String | None

class validate_actions.domain_model.ast.Secrets(pos, inherit=False, secrets=<factory>)[source]¶

Bases: object

Secret configuration for reusable workflow calls.

Manages how secrets are passed to called workflows.

Parameters:

pos (Pos)
inherit (bool)
secrets (Dict[String, String])

pos¶

Position in source file for error reporting

Type:: Pos

inherit¶

Whether to inherit all secrets from calling workflow

Type:: bool

secrets¶

Explicit secret mappings

Type:: Dict[String, String]

class validate_actions.domain_model.ast.Job(pos, job_id_, steps_, contexts, name_=None, permissions_=<factory>, needs_=None, if_=None, runs_on_=None, environment_=None, concurrency_=None, outputs_=None, env_=None, defaults_=None, timeout_minutes_=None, strategy_=None, container_=None, services_=None, uses_=None, with_=<factory>, secrets_=None)[source]¶

Bases: object

Individual job within a workflow.

Jobs are the main execution units that run on specific runners. They contain steps and can depend on other jobs.

Parameters:

pos (Pos)
job_id_ (str)
steps_ (List[Step])
contexts (Contexts)
name_ (String | None)
permissions_ (Permissions)
needs_ (List[String] | None)
if_ (String | None)
runs_on_ (RunsOn | None)
environment_ (Environment | None)
concurrency_ (Concurrency | None)
outputs_ (None)
env_ (Env | None)
defaults_ (Defaults | None)
timeout_minutes_ (int | None)
strategy_ (Strategy | None)
container_ (Container | None)
services_ (None)
uses_ (String | None)
with_ (Dict[String, String])
secrets_ (Secrets | None)

pos¶

Position in source file for error reporting

Type:: Pos

job_id_¶

Unique identifier for this job

Type:: str

steps_¶

Ordered list of steps to execute

Type:: List[Step]

contexts¶

Available contexts for expression validation

Type:: Contexts

name_¶

Human-readable job name

Type:: String | None

permissions_¶

Job-level permission overrides

Type:: Permissions

needs_¶

List of job IDs this job depends on

Type:: List[String] | None

if_¶

Conditional expression to determine if job should run

Type:: String | None

runs_on_¶

Runner selection configuration

Type:: RunsOn | None

environment_¶

Deployment environment settings

Type:: Environment | None

concurrency_¶

Job-level concurrency controls

Type:: Concurrency | None

outputs_¶

Job outputs for use by dependent jobs

Type:: None

env_¶

Job-level environment variables

Type:: Env | None

defaults_¶

Default settings for run steps

Type:: Defaults | None

timeout_minutes_¶

Maximum job execution time

Type:: int | None

strategy_¶

Matrix execution strategy

Type:: Strategy | None

container_¶

Container to run job in

Type:: Container | None

services_¶

Service containers for job

Type:: None

uses_¶

Reusable workflow reference (alternative to steps)

Type:: String | None

with_¶

Inputs for reusable workflow calls

Type:: Dict[String, String]

secrets_¶

Secret configuration for reusable workflow calls

Type:: Secrets | None

class validate_actions.domain_model.ast.Step(pos, exec, contexts, id_=None, if_=None, name_=None, env_=None, continue_on_error_=None, timeout_minutes_=None)[source]¶

Bases: object

Individual step within a job.

Steps are the atomic execution units that either run shell commands or invoke GitHub Actions.

Parameters:

pos (Pos)
exec (Exec)
contexts (Contexts)
id_ (String | None)
if_ (String | None)
name_ (String | None)
env_ (Env | None)
continue_on_error_ (bool | None)
timeout_minutes_ (int | None)

pos¶

Position in source file for error reporting

Type:: Pos

exec¶

The action or command to execute

Type:: Exec

contexts¶

Available contexts for expression validation

Type:: Contexts

id_¶

Optional step identifier for referencing outputs

Type:: String | None

if_¶

Conditional expression to determine if step should run

Type:: String | None

name_¶

Human-readable step name

Type:: String | None

env_¶

Step-level environment variables

Type:: Env | None

continue_on_error_¶

Whether job should continue if step fails

Type:: bool | None

timeout_minutes_¶

Maximum step execution time

Type:: int | None

class validate_actions.domain_model.ast.Exec[source]¶

Bases: ABC

Abstract base class for step execution types.

Steps can either run shell commands or invoke GitHub Actions.

class validate_actions.domain_model.ast.ActionMetadata(required_inputs=<factory>, possible_inputs=<factory>, version_tags=<factory>, outputs=<factory>)[source]¶

Bases: object

Metadata about a GitHub Action for validation.

Retrieved from GitHub API or action.yml files to validate action usage and provide auto-completion.

Parameters:

required_inputs (List[str])
possible_inputs (List[str])
version_tags (List[Dict])
outputs (Dict[str, str])

required_inputs¶

List of mandatory input parameter names

Type:: List[str]

possible_inputs¶

List of all supported input parameter names

Type:: List[str]

version_tags¶

Available version tags for the action

Type:: List[Dict]

outputs¶

Dictionary mapping output names to descriptions

Type:: Dict[str, str]

class validate_actions.domain_model.ast.ExecAction(pos, uses_, with_, metadata=None, with_args_=None, with_entrypoint_=None)[source]¶

Bases: Exec

Step that executes a GitHub Action.

Invokes reusable actions from GitHub Marketplace or repositories.

Parameters:

pos (Pos)
uses_ (String)
with_ (Dict[String, String])
metadata (ActionMetadata | None)
with_args_ (String | None)
with_entrypoint_ (String | None)

pos¶

Position in source file for error reporting

Type:: Pos

uses_¶

Action reference (org/repo@version)

Type:: String

with_¶

Input parameters for the action

Type:: Dict[String, String]

metadata¶

Optional action metadata for validation

Type:: ActionMetadata | None

with_args_¶

Override action args (Docker actions)

Type:: String | None

with_entrypoint_¶

Override action entrypoint (Docker actions)

Type:: String | None

class validate_actions.domain_model.ast.ExecRun(pos, run_, shell_=None, working_directory_=None)[source]¶

Bases: Exec

Step that executes shell commands.

Runs arbitrary shell commands on the runner.

Parameters:

pos (Pos)
run_ (String)
shell_ (String | None)
working_directory_ (String | None)

pos¶

Position in source file for error reporting

Type:: Pos

run_¶

Shell command(s) to execute

Type:: String

shell_¶

Shell to use for execution

Type:: String | None

working_directory_¶

Directory to run commands in

Type:: String | None

validate_actions.domain_model.ast¶

validate-actions

Navigation

Related Topics