workflow

Overview ¶

Package workflow provides agent file and feature support validation.

Agent Validation ¶

This file validates agent-specific configuration and feature compatibility for agentic workflows. It ensures that:

• Custom agent files exist when specified
• Engine features are supported (HTTP transport, max-turns, web-search)
• Workflow triggers have appropriate security constraints

Validation Functions ¶

• validateAgentFile() - Validates custom agent file exists
• validateHTTPTransportSupport() - Validates HTTP MCP compatibility with engine
• validateMaxTurnsSupport() - Validates max-turns feature support
• validateWebSearchSupport() - Validates web-search feature support (warning)
• validateWorkflowRunBranches() - Validates workflow_run has branch restrictions

Validation Patterns ¶

This file uses several patterns:

• File existence validation: Agent files
• Feature compatibility checks: Engine capabilities
• Security validation: workflow_run branch restrictions
• Warning vs error: Some validations warn instead of fail

Security Considerations ¶

The validateWorkflowRunBranches function enforces security best practices:

• In strict mode: Errors when workflow_run lacks branch restrictions
• In normal mode: Warns when workflow_run lacks branch restrictions

When to Add Validation Here ¶

Add validation to this file when:

• It validates custom agent file configuration
• It checks engine feature compatibility
• It validates agent-specific requirements
• It enforces security constraints on triggers

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides JavaScript bundling for agentic workflows.

JavaScript Bundler with Runtime Mode Support ¶

The bundler supports two runtime environments:

1. GitHub Script Mode (RuntimeModeGitHubScript)

• Used for JavaScript embedded in GitHub Actions YAML via actions/github-script
• No module system available (no require() or module.exports at runtime)
• All local requires must be bundled inline
• All module.exports statements are removed
• Validation ensures no local requires or module references remain

2. Node.js Mode (RuntimeModeNodeJS)

• Used for standalone Node.js scripts that run on filesystem
• Full CommonJS module system available
• module.exports statements are preserved
• Local requires can remain if modules are available on filesystem
• Less aggressive bundling and validation

Usage ¶

For GitHub Script mode (default for backward compatibility):

bundled, err := BundleJavaScriptFromSources(mainContent, sources, "")
// or explicitly:
bundled, err := BundleJavaScriptWithMode(mainContent, sources, "", RuntimeModeGitHubScript)

For Node.js mode:

bundled, err := BundleJavaScriptWithMode(mainContent, sources, "", RuntimeModeNodeJS)

Guardrails and Validation ¶

The bundler includes several guardrails based on runtime mode:

- validateNoLocalRequires: Ensures all local requires (./... or ../...) are bundled (GitHub Script mode only) - validateNoModuleReferences: Ensures no module.exports or exports.* remain (GitHub Script mode only) - removeExports: Strips module.exports from bundled code (GitHub Script mode only)

These validations prevent runtime errors when JavaScript is executed in environments without a module system.

Package workflow provides JavaScript bundling for agentic workflows.

File Mode Bundler ¶

This file implements a file-based bundling mode for GitHub Script actions that writes JavaScript files to disk instead of inlining them in YAML. This approach maximizes reuse of helper modules within the same job.

How it works ¶

1. CollectScriptFiles - Recursively collects all JavaScript files used by a script 2. GenerateWriteScriptsStep - Creates a step that writes all files to /tmp/gh-aw/scripts/ 3. GenerateRequireScript - Converts a script to require from the local filesystem

Benefits ¶

• Reduces YAML size by avoiding duplicate inlined code
• Maximizes reuse of helper modules within the same job
• Makes debugging easier (files exist on disk during execution)
• Reduces memory pressure from large bundled strings

Package workflow provides JavaScript bundler validation for agentic workflows.

JavaScript Bundler Validation ¶

This file validates bundled JavaScript to ensure compatibility with the target runtime mode. Validation functions prevent runtime errors from missing modules or incompatible module references.

Runtime Mode Validation ¶

GitHub Script Mode:

• validateNoLocalRequires() - Ensures all local require() statements are inlined
• validateNoModuleReferences() - Ensures no module.exports or exports.* remain

Node.js Mode:

• No strict validation - module.exports and local requires are allowed

Validation Functions ¶

• validateNoLocalRequires() - Validates bundled JavaScript has no local require() statements
• validateNoModuleReferences() - Validates no module.exports or exports references remain
• isInsideStringLiteralAt() - Helper to detect if a position is inside a string literal

Validation Pattern: Bundling Verification ¶

Bundler validation ensures that local require() statements are inlined:

• Scans bundled JavaScript for require('./...') or require('../...') patterns
• Ignores require statements inside string literals
• Returns hard errors if local requires are found (indicates bundling failure)
• Helps prevent runtime module-not-found errors

When to Add Validation Here ¶

Add validation to this file when:

• It validates JavaScript bundling correctness
• It checks for missing module dependencies
• It validates CommonJS require() statement resolution
• It validates JavaScript code structure based on runtime mode

For bundling functions, see bundler.go. For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides helper functions for closing GitHub entities.

This file contains shared utilities for building close entity jobs (issues, pull requests, discussions). These helpers extract common patterns used across the three close entity implementations to reduce code duplication and ensure consistency in configuration parsing and job generation.

Organization Rationale ¶

These close entity helpers are grouped here because they:

• Provide generic close entity functionality used by 3 entity types
• Share common configuration patterns (target, filters, max)
• Follow a consistent entity registry pattern
• Enable DRY principles for close operations

This follows the helper file conventions documented in the developer instructions. See skills/developer/SKILL.md#helper-file-conventions for details.

Key Functions ¶

Configuration Parsing:

• parseCloseEntityConfig() - Generic close entity configuration parser
• parseCloseIssuesConfig() - Parse close-issue configuration
• parseClosePullRequestsConfig() - Parse close-pull-request configuration
• parseCloseDiscussionsConfig() - Parse close-discussion configuration

Entity Registry:

• closeEntityRegistry - Central registry of all close entity definitions
• closeEntityDefinition - Definition structure for close entity types

Usage Patterns ¶

The close entity helpers follow a registry pattern where each entity type (issue, pull request, discussion) is defined with its specific parameters (config keys, environment variables, permissions, scripts). This allows:

• Consistent configuration parsing across entity types
• Easy addition of new close entity types
• Centralized entity type definitions

When to Use vs Alternatives ¶

Use these helpers when:

• Implementing close operations for GitHub entities
• Parsing close entity configurations from workflow YAML
• Building close entity jobs with consistent patterns

For create/update operations, see:

• create_*.go files for entity creation logic
• update_entity_helpers.go for entity update logic

Package workflow provides validation for GitHub Actions event filter mutual exclusivity.

Filter Validation ¶

This file validates that event filters follow GitHub Actions requirements for mutual exclusivity. GitHub Actions rejects workflows that specify both:

• branches and branches-ignore in the same event
• paths and paths-ignore in the same event

Validation Functions ¶

• ValidateEventFilters() - Main entry point for filter validation
• validateFilterExclusivity() - Validates a single event's filter configuration

GitHub Actions Requirements ¶

From GitHub Actions documentation:

• You cannot use both branches and branches-ignore filters for the same event
• You cannot use both paths and paths-ignore filters for the same event

These restrictions apply to push and pull_request event filters.

When to Add Validation Here ¶

Add validation to this file when:

• It validates event filter configurations
• It checks for GitHub Actions filter requirements
• It validates mutual exclusivity of filter options

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides helper functions for parsing safe output configurations.

This file contains parsing utilities for extracting and validating configuration values from safe output config maps. These helpers are used across safe output processors to parse common configuration patterns.

Organization Rationale ¶

These parse functions are grouped in a helper file because they:

• Share a common purpose (safe output config parsing)
• Are used by multiple safe output modules (3+ callers)
• Provide stable, reusable parsing patterns
• Have clear domain focus (configuration extraction)

This follows the helper file conventions documented in the developer instructions. See skills/developer/SKILL.md#helper-file-conventions for details.

Key Functions ¶

Configuration Array Parsing:

• ParseStringArrayFromConfig() - Generic string array extraction
• parseLabelsFromConfig() - Extract labels array
• parseParticipantsFromConfig() - Extract participants array
• parseAllowedReposFromConfig() - Extract allowed repos array
• parseAllowedLabelsFromConfig() - Extract allowed labels array

Configuration String Parsing:

• extractStringFromMap() - Generic string extraction
• parseTitlePrefixFromConfig() - Extract title prefix
• parseTargetRepoFromConfig() - Extract target repository
• parseTargetRepoWithValidation() - Extract and validate target repo

Configuration Integer Parsing:

• parseExpiresFromConfig() - Extract expiration time
• parseRelativeTimeSpec() - Parse relative time specifications

Package workflow provides Docker image validation for agentic workflows.

Docker Image Validation ¶

This file validates Docker container images used in MCP configurations. Validation ensures that Docker images specified in workflows exist and are accessible, preventing runtime failures due to typos or non-existent images.

Validation Functions ¶

• validateDockerImage() - Validates a single Docker image exists and is accessible

Validation Pattern: Warning vs Error ¶

Docker image validation uses a flexible approach:

• If Docker is not available, a warning is emitted but validation is skipped
• If an image cannot be pulled due to authentication (private repo), validation passes
• If an image truly doesn't exist, validation fails with an error
• Verbose mode provides detailed validation feedback

When to Add Validation Here ¶

Add validation to this file when:

• It validates Docker images
• It checks container image accessibility
• It validates Docker-specific configurations

For Docker image collection functions, see docker.go. For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides shared helper functions for AI engine implementations.

This file contains utilities used across multiple AI engine files (copilot_engine.go, claude_engine.go, codex_engine.go, custom_engine.go) to generate common workflow steps and configurations.

Organization Rationale ¶

These helper functions are grouped here because they:

• Are used by 3+ engine implementations (shared utilities)
• Provide common patterns for agent installation and npm setup
• Have a clear domain focus (engine workflow generation)
• Are stable and change infrequently

This follows the helper file conventions documented in skills/developer/SKILL.md.

Key Functions ¶

Agent Installation:

• GenerateAgentInstallSteps() - Generate agent installation workflow steps

NPM Installation:

• GenerateNpmInstallStep() - Generate npm package installation step
• GenerateEngineDependenciesInstallStep() - Generate engine dependencies install step

Configuration:

• GetClaudeSystemPrompt() - Get system prompt for Claude engine

These functions encapsulate shared logic that would otherwise be duplicated across engine files, maintaining DRY principles while keeping engine-specific code separate.

Package workflow provides engine validation for agentic workflows.

Engine Validation ¶

This file validates engine configurations used in agentic workflows. Validation ensures that engine IDs are supported and that only one engine specification exists across the main workflow and all included files.

Validation Functions ¶

• validateEngine() - Validates that a given engine ID is supported
• validateSingleEngineSpecification() - Validates that only one engine field exists across all files

Validation Pattern: Engine Registry ¶

Engine validation uses the compiler's engine registry:

• Supports exact engine ID matching (e.g., "copilot", "claude")
• Supports prefix matching for backward compatibility (e.g., "codex-experimental")
• Empty engine IDs are valid and use the default engine
• Detailed logging of validation steps for debugging

When to Add Validation Here ¶

Add validation to this file when:

• It validates engine IDs or engine configurations
• It checks engine registry entries
• It validates engine-specific settings
• It validates engine field consistency across imports

For engine configuration extraction, see engine.go. For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides GitHub Actions expression security validation.

Expression Safety Validation ¶

This file validates that GitHub Actions expressions used in workflow markdown are safe and authorized. It prevents injection attacks and ensures workflows only use approved expression patterns.

Validation Functions ¶

• validateExpressionSafety() - Validates all expressions in markdown content
• validateSingleExpression() - Validates individual expression syntax

Validation Pattern: Allowlist Security ¶

Expression validation uses a strict allowlist approach:

• Only pre-approved GitHub context expressions are allowed
• Unauthorized expressions cause compilation to fail
• Prevents injection of secrets or environment variables
• Uses regex patterns to match allowed expression formats

Allowed Expression Patterns ¶

Expressions must match one of these patterns:

• github.event.* (event context properties)
• github.actor, github.repository, etc. (core GitHub context)
• needs.*.outputs.* (job dependencies)
• steps.*.outputs.* (step outputs)
• github.event.inputs.* (workflow_dispatch inputs)

See pkg/constants for the complete list of allowed expressions.

When to Add Validation Here ¶

Add validation to this file when:

• It validates GitHub Actions expression parsing
• It enforces expression security policies
• It prevents expression injection attacks
• It validates expression syntax and structure

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides Git repository utilities for workflow compilation.

This file contains helper functions for interacting with Git repositories to extract metadata such as tags and version information. These helpers are used during workflow compilation to determine release contexts and versioning.

Organization Rationale ¶

These Git utilities are grouped in a helper file because they:

• Provide Git-specific functionality (tags, versions)
• Are used by multiple workflow compilation modules
• Encapsulate Git command execution and error handling
• Have a clear domain focus (Git repository metadata)

This follows the helper file conventions documented in the developer instructions. See skills/developer/SKILL.md#helper-file-conventions for details.

Key Functions ¶

Tag Detection:

• GetCurrentGitTag() - Detect current Git tag from environment or repository

Usage Patterns ¶

These functions are primarily used during workflow compilation to:

• Detect release contexts (tags vs. regular commits)
• Extract version information for releases
• Support conditional workflow behavior based on Git state

Package workflow provides generic map and type conversion utilities.

This file contains low-level helper functions for working with map[string]any structures and type conversions. These utilities are used throughout the workflow compilation process to safely parse and manipulate configuration data.

Organization Rationale ¶

These functions are grouped in a helper file because they:

• Provide generic, reusable utilities (used by 10+ files)
• Have no specific domain focus (work with any map/type data)
• Are small, stable functions (< 50 lines each)
• Follow clear, single-purpose patterns

This follows the helper file conventions documented in skills/developer/SKILL.md.

Key Functions ¶

Type Conversion:

• parseIntValue() - Safely parse numeric types to int with truncation warnings

Map Operations:

• filterMapKeys() - Create new map excluding specified keys

These utilities handle common type conversion and map manipulation patterns that occur frequently during YAML-to-struct parsing and configuration processing.

Package workflow provides MCP (Model Context Protocol) configuration validation.

MCP Configuration Validation ¶

This file validates MCP server configurations in agentic workflows. It ensures that MCP configurations have required fields, correct types, and satisfy type-specific requirements (stdio vs http).

Validation Functions ¶

• ValidateMCPConfigs() - Validates all MCP configurations in tools section
• validateStringProperty() - Validates that a property is a string type
• validateMCPRequirements() - Validates type-specific MCP requirements

Validation Pattern: Schema and Requirements Validation ¶

MCP validation uses multiple patterns:

• Type inference: Determines MCP type from fields if not explicit
• Required field validation: Ensures necessary fields exist
• Type-specific validation: Different requirements for stdio vs http
• Property type checking: Validates field types match expectations

MCP Types and Requirements ¶

## stdio type

• Requires either 'command' or 'container' (but not both)
• Optional: version, args, entrypointArgs, env, proxy-args, registry

## http type

• Requires 'url' field
• Cannot use 'container' field
• Optional: headers, registry

When to Add Validation Here ¶

Add validation to this file when:

• It validates MCP server configuration
• It checks MCP-specific field requirements
• It validates MCP type compatibility
• It ensures MCP configuration correctness

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides NPM package extraction utilities for agentic workflows.

NPM Package Extraction ¶

This file provides utilities to extract NPM package names from workflow data for packages used with npx (Node Package Execute). The extracted packages can be validated by the validation functions in validation.go.

Extraction Functions ¶

• extractNpxPackages() - Extracts npm packages used with npx launcher
• extractNpxFromCommands() - Parses command strings to find npx packages

For package validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides NPM package validation for agentic workflows.

NPM Package Validation ¶

This file validates NPM package availability on the npm registry for packages used with npx (Node Package Execute). Validation ensures that Node.js packages specified in workflows exist and can be installed at runtime.

Validation Functions ¶

• validateNpxPackages() - Validates npm packages used with npx launcher

Validation Pattern: External Registry Check ¶

NPM package validation queries the npm registry using the npm CLI:

• Uses `npm view <package> name` to check package existence
• Returns hard errors if packages don't exist (unlike pip validation)
• Requires npm to be installed on the system

When to Add Validation Here ¶

Add validation to this file when:

• It validates Node.js/npm ecosystem packages
• It checks npm registry package existence
• It validates npx launcher packages
• It validates Node.js version compatibility

For package extraction functions, see npm.go. For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides generic package extraction utilities for agentic workflows.

Package Extraction Framework ¶

This file provides a reusable, configurable framework for extracting package names from command strings. The PackageExtractor type eliminates code duplication by providing a single abstraction that handles different package managers (npm, pip, uv, go, etc.) with minimal configuration.

Purpose and Benefits ¶

The PackageExtractor pattern exists to:

• Prevent code duplication across package manager extraction functions
• Provide a consistent interface for command parsing
• Centralize package name extraction logic
• Reduce maintenance burden by having a single implementation

Usage Pattern ¶

Instead of implementing custom extraction logic, configure a PackageExtractor with the appropriate settings for your package manager:

extractor := PackageExtractor{
    CommandNames:       []string{"pip", "pip3"},
    RequiredSubcommand: "install",
    TrimSuffixes:       "&|;",
}
packages := extractor.ExtractPackages("pip install requests")
// Returns: []string{"requests"}

Package Manager Examples ¶

NPM (npx):

extractor := PackageExtractor{
    CommandNames:       []string{"npx"},
    RequiredSubcommand: "",           // No subcommand needed
    TrimSuffixes:       "&|;",
}
packages := extractor.ExtractPackages("npx @playwright/mcp@latest")
// Returns: []string{"@playwright/mcp@latest"}

Python (pip):

extractor := PackageExtractor{
    CommandNames:       []string{"pip", "pip3"},
    RequiredSubcommand: "install",    // Must have "install" subcommand
    TrimSuffixes:       "&|;",
}
packages := extractor.ExtractPackages("pip install requests==2.28.0")
// Returns: []string{"requests==2.28.0"}

Go (with multiple subcommands):

extractor := PackageExtractor{
    CommandNames:        []string{"go"},
    RequiredSubcommands: []string{"install", "get"},
    TrimSuffixes:        "&|;",
}
packages := extractor.ExtractPackages("go install github.com/user/tool@v1.0.0")
// Returns: []string{"github.com/user/tool@v1.0.0"}

Python (uv):

extractor := PackageExtractor{
    CommandNames:       []string{"uvx"},
    RequiredSubcommand: "",
    TrimSuffixes:       "&|;",
}
packages := extractor.ExtractPackages("uvx black")
// Returns: []string{"black"}

Best Practices ¶

• ALWAYS use PackageExtractor instead of reimplementing extraction logic
• Configure CommandNames for all variations of the command (e.g., ["pip", "pip3"])
• Set RequiredSubcommand only when the package manager requires it (e.g., "install" for pip)
• Include common shell operators in TrimSuffixes (typically "&|;")
• For special cases, use the exported FindPackageName method to reuse logic

Configuration Details ¶

• CommandNames: List of command names to match (case-sensitive)
• RequiredSubcommand: Subcommand that must appear before the package name (empty string if package comes directly after command)
• TrimSuffixes: Characters to remove from the end of package names (useful for shell operators like "&", "|", ";")

For package-specific extraction implementations, see:

• npm.go (npx packages)
• pip.go (pip and uv packages)
• dependabot.go (go packages)

For package validation, see validation.go.

Package workflow provides Python package extraction for agentic workflows.

Python Package Extraction ¶

This file extracts Python package names from workflow configurations using pip and uv package managers. Extraction functions parse commands and configuration to identify packages that will be installed at runtime.

Extraction Functions ¶

• extractPipPackages() - Extracts pip packages from workflow configuration
• extractPipFromCommands() - Extracts pip packages from command strings
• extractUvPackages() - Extracts uv packages from workflow configuration
• extractUvFromCommands() - Extracts uv packages from command strings

When to Add Extraction Here ¶

Add extraction to this file when:

• It parses Python/pip ecosystem package names
• It identifies packages from shell commands
• It extracts packages from workflow steps
• It detects uv package manager usage

For package validation functions, see pip_validation.go. For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides Python package validation for agentic workflows.

Python Package Validation ¶

This file validates Python package availability on PyPI using pip and uv package managers. Validation ensures that Python packages specified in workflows exist and can be installed at runtime, preventing failures due to typos or non-existent packages.

Validation Functions ¶

• validatePythonPackagesWithPip() - Generic pip validation helper
• validatePipPackages() - Validates pip packages from workflow configuration
• validateUvPackages() - Validates uv packages from workflow configuration
• validateUvPackagesWithPip() - Validates uv packages using pip index

Validation Pattern: Warning vs Error ¶

Python package validation uses a warning-based approach rather than hard errors:

• If pip validation fails, a warning is emitted but compilation continues
• This allows for experimental packages or packages not yet published
• Verbose mode provides detailed validation feedback

When to Add Validation Here ¶

Add validation to this file when:

• It validates Python/pip ecosystem packages
• It checks PyPI package existence
• It validates Python version compatibility
• It validates uv package manager packages

For package extraction functions, see pip.go. For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides helper functions for generating prompt workflow steps.

This file contains utilities for building GitHub Actions workflow steps that append prompt text to prompt files used by AI engines. These helpers extract common patterns used across multiple prompt generators (XPIA, temp folder, playwright, edit tool, etc.) to reduce code duplication and ensure security.

Organization Rationale ¶

These prompt step helpers are grouped here because they:

• Provide common patterns for prompt text generation used by 5+ generators
• Handle GitHub Actions expression extraction for security
• Ensure consistent prompt step formatting across engines
• Centralize template injection prevention logic

This follows the helper file conventions documented in the developer instructions. See skills/developer/SKILL.md#helper-file-conventions for details.

Key Functions ¶

Static Prompt Generation:

• generateStaticPromptStep() - Generate steps for static prompt text
• generateStaticPromptStepWithExpressions() - Generate steps with secure expression handling

Usage Patterns ¶

These helpers are used when generating workflow steps that append text to prompt files. They follow two patterns:

1. **Static Text** (no GitHub Actions expressions): ```go generateStaticPromptStep(yaml, "Append XPIA security instructions to prompt", xpiaPromptText, data.SafetyPrompt) ```

2. **Text with Expressions** (contains ${{ ... }}): ```go generateStaticPromptStepWithExpressions(yaml, "Append dynamic context to prompt", promptWithExpressions, shouldInclude) ```

The expression-aware helper extracts GitHub Actions expressions into environment variables to prevent template injection vulnerabilities.

Security Considerations ¶

Always use generateStaticPromptStepWithExpressions() when prompt text contains GitHub Actions expressions (${{ ... }}). This ensures:

• Expressions are evaluated in controlled env: context
• No inline shell script interpolation (prevents injection)
• Safe placeholder substitution via JavaScript

See specs/template-injection-prevention.md for security details.

When to Use vs Alternatives ¶

Use these helpers when:

• Generating workflow steps that append text to prompt files
• Working with static or expression-containing prompt text
• Need consistent prompt step formatting across engines

For other prompt-related functionality, see:

• *_engine.go files for engine-specific prompt generation
• engine_helpers.go for shared engine utilities

Package workflow provides repository memory configuration and validation.

This file handles:

• Repo-memory configuration structures and defaults
• Repo-memory tool configuration extraction and parsing
• Generation of per-memory GitHub token secrets
• Domain-specific validation for repo-memory configurations

Validation Functions ¶

This file contains domain-specific validation functions for repo-memory:

• validateNoDuplicateMemoryIDs() - Ensures unique memory identifiers

These validation functions are co-located with repo-memory logic following the principle that domain-specific validation belongs in domain files. See validation.go for the validation architecture documentation.

Package workflow provides repository feature detection and validation.

Repository Features Validation ¶

This file validates that required repository features (discussions, issues) are enabled when safe-outputs are configured that depend on them. It provides caching to minimize API calls when checking repository capabilities.

Validation Functions ¶

• validateRepositoryFeatures() - Main orchestrator validating safe-outputs requirements
• getCurrentRepository() - Gets current repository from git context (cached)
• getRepositoryFeatures() - Gets repository features with caching (discussions, issues)
• checkRepositoryHasDiscussions() - Checks if discussions are enabled (cached)
• checkRepositoryHasIssues() - Checks if issues are enabled (cached)
• ClearRepositoryFeaturesCache() - Clears all repository feature caches

Validation Pattern: Feature Detection with Caching ¶

Repository feature validation uses a caching pattern to amortize expensive API calls:

• sync.Map for thread-safe cache storage
• sync.Once for single-fetch guarantee
• Atomic LoadOrStore for race-free caching
• Separate logged cache to avoid duplicate success messages

When to Add Validation Here ¶

Add validation to this file when:

• It checks repository capabilities (discussions, issues, projects, etc.)
• It validates safe-outputs dependencies on repository features
• It requires GitHub API calls to check repository settings
• It benefits from caching to reduce API usage

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides runtime validation for packages, containers, and expressions.

Runtime Validation ¶

This file validates runtime dependencies and configuration for agentic workflows. It ensures that:

• Container images exist and are accessible
• Runtime packages (npm, pip, uv) are available
• Expression sizes don't exceed GitHub Actions limits
• Secret references are valid
• Cache IDs are unique

Validation Functions ¶

• validateExpressionSizes() - Validates expression size limits (21KB max)
• validateContainerImages() - Validates Docker images exist
• validateRuntimePackages() - Validates npm, pip, uv packages
• collectPackagesFromWorkflow() - Generic package collection helper
• validateNoDuplicateCacheIDs() - Validates unique cache-memory IDs
• validateSecretReferences() - Validates secret name format

Validation Patterns ¶

This file uses several patterns:

• External resource validation: Docker images, npm/pip packages
• Size limit validation: Expression sizes, file sizes
• Format validation: Secret names, cache IDs
• Collection and deduplication: Package extraction

Size Limits ¶

GitHub Actions has a 21KB limit for expression values including environment variables. This validation prevents compilation of workflows that will fail at runtime.

When to Add Validation Here ¶

Add validation to this file when:

• It validates runtime dependencies (packages, containers)
• It checks expression or content size limits
• It validates configuration format (secrets, cache IDs)
• It requires external resource checking

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides sandbox configuration and validation for agentic workflows.

This file handles:

• Sandbox type definitions (AWF, SRT)
• Sandbox configuration structures and parsing
• Sandbox runtime config generation
• Domain-specific validation for sandbox configurations

Validation Functions ¶

This file contains domain-specific validation functions for sandbox configuration:

• validateMountsSyntax() - Validates container mount syntax
• validateSandboxConfig() - Validates complete sandbox configuration

These validation functions are co-located with sandbox logic following the principle that domain-specific validation belongs in domain files. See validation.go for the validation architecture documentation.

Package workflow provides GitHub Actions schema validation for compiled workflows.

GitHub Actions Schema Validation ¶

This file validates that compiled workflow YAML conforms to the official GitHub Actions workflow schema. It uses JSON Schema validation with caching to avoid recompiling the schema on every validation.

Validation Functions ¶

• validateGitHubActionsSchema() - Validates YAML against GitHub Actions schema
• getCompiledSchema() - Returns cached compiled schema (compiled once)

Validation Pattern: Schema Validation with Caching ¶

Schema validation uses a singleton pattern for efficiency:

• sync.Once ensures schema is compiled only once
• Schema is embedded in the binary as githubWorkflowSchema
• Cached compiled schema is reused across all validations
• YAML is parsed directly and validated without JSON conversion

Schema Source ¶

The GitHub Actions workflow schema is embedded from:

https://json.schemastore.org/github-workflow.json

When to Add Validation Here ¶

Add validation to this file when:

• It validates against JSON schemas
• It checks GitHub Actions YAML structure
• It verifies workflow syntax correctness
• It requires schema compilation and caching

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides a ScriptRegistry for managing JavaScript script bundling.

Script Registry Pattern ¶

The ScriptRegistry eliminates the repetitive sync.Once pattern found throughout the codebase for lazy script bundling. Instead of declaring separate variables and getter functions for each script, register scripts once and retrieve them by name with runtime mode verification.

Before (repetitive pattern): ¶

var (
    createIssueScript     string
    createIssueScriptOnce sync.Once
)

func getCreateIssueScript() string {
    createIssueScriptOnce.Do(func() {
        sources := GetJavaScriptSources()
        bundled, err := BundleJavaScriptFromSources(createIssueScriptSource, sources, "")
        if err != nil {
            createIssueScript = createIssueScriptSource
        } else {
            createIssueScript = bundled
        }
    })
    return createIssueScript
}

After (using registry with runtime mode verification): ¶

// Registration at package init
DefaultScriptRegistry.RegisterWithMode("create_issue", createIssueScriptSource, RuntimeModeGitHubScript)

// Usage anywhere with mode verification
script := DefaultScriptRegistry.GetWithMode("create_issue", RuntimeModeGitHubScript)

Benefits ¶

• Eliminates ~15 lines of boilerplate per script (variable pair + getter function)
• Centralizes bundling logic
• Consistent error handling
• Thread-safe lazy initialization
• Easy to add new scripts
• Runtime mode verification prevents mismatches between registration and usage

Runtime Mode Verification ¶

The GetWithMode() method verifies that the requested runtime mode matches the mode the script was registered with. This catches configuration errors at compile time rather than at runtime. If there's a mismatch, a warning is logged but the script is still returned to avoid breaking workflows.

Package workflow provides embedded JavaScript scripts for GitHub Actions workflows.

Script Registry Pattern ¶

This file uses the ScriptRegistry pattern to manage lazy bundling of JavaScript scripts. Instead of having separate sync.Once patterns for each script, all scripts are registered with the DefaultScriptRegistry and bundled on-demand.

See script_registry.go for the ScriptRegistry implementation.

Package workflow provides strict mode security validation for agentic workflows.

Strict Mode Validation ¶

This file contains strict mode validation functions that enforce security and safety constraints when workflows are compiled with the --strict flag.

Strict mode is designed for production workflows that require enhanced security guarantees. It enforces constraints on:

• Write permissions on sensitive scopes
• Network access configuration
• Custom MCP server network settings
• Bash wildcard tool usage

Validation Functions ¶

The strict mode validator performs progressive validation:

1. validateStrictMode() - Main orchestrator that coordinates all strict mode checks
2. validateStrictPermissions() - Refuses write permissions on sensitive scopes
3. validateStrictNetwork() - Requires explicit network configuration
4. validateStrictMCPNetwork() - Requires network config on custom MCP servers

Integration with Security Scanners ¶

Strict mode also affects the zizmor security scanner behavior (see pkg/cli/zizmor.go). When zizmor is enabled with --zizmor flag, strict mode treats any security findings as compilation errors rather than warnings.

When to Add Validation Here ¶

Add validation to this file when:

• It enforces a strict mode security policy
• It restricts permissions or access in production workflows
• It validates network access controls
• It enforces tool usage restrictions for security

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides utilities for processing GitHub Agentic Workflows.

String Processing Patterns ¶

This package implements two distinct patterns for string processing:

## Sanitize Pattern: Character Validity

Sanitize functions remove or replace invalid characters to create valid identifiers, file names, or artifact names. Use sanitize functions when you need to ensure a string contains only valid characters for a specific context.

Functions:

• SanitizeName: Configurable sanitization with character preservation options
• SanitizeWorkflowName: Sanitizes for artifact names and file paths (preserves dots, underscores)
• SanitizeIdentifier (workflow_name.go): Creates clean identifiers for user agents

Example:

// User input with invalid characters
input := "My Workflow: Test/Build"
result := SanitizeWorkflowName(input)
// Returns: "my-workflow-test-build"

## Normalize Pattern: Format Standardization

Normalize functions standardize format by removing extensions, converting between naming conventions, or applying consistent formatting rules. Use normalize functions when converting between different representations of the same logical entity.

Functions:

• normalizeWorkflowName (resolve.go): Removes file extensions (.md, .lock.yml)
• normalizeSafeOutputIdentifier (safe_outputs.go): Converts dashes to underscores

Example:

// File name to base identifier
input := "weekly-research.md"
result := normalizeWorkflowName(input)
// Returns: "weekly-research"

## When to Use Each Pattern

Use SANITIZE when:

• Processing user input that may contain invalid characters
• Creating identifiers, artifact names, or file paths
• Need to ensure character validity for a specific context

Use NORMALIZE when:

• Converting between file names and identifiers (removing extensions)
• Standardizing naming conventions (dashes to underscores)
• Input is already valid but needs format conversion

See specs/string-sanitization-normalization.md for detailed guidance.

Package workflow provides template structure validation for agentic workflows.

Template Validation ¶

This file validates template conditionals and their interaction with other workflow features. It ensures that import directives and template regions don't conflict.

Validation Functions ¶

• validateNoIncludesInTemplateRegions() - Validates that imports are not inside template blocks

Validation Pattern: Structure Validation ¶

Template validation uses structure checking:

• Parses template conditional blocks ({{#if...}}{{/if}})
• Checks for import directives within template regions
• Prevents import processing conflicts with template rendering

When to Add Validation Here ¶

Add validation to this file when:

• It validates template structure or syntax
• It checks template conditional blocks
• It validates template-related features
• It ensures template compatibility with other features

For general validation, see validation.go. For detailed documentation, see specs/validation-architecture.md

Package workflow provides tool configuration parsing for agentic workflows.

This file handles parsing of tool configurations from the frontmatter tools section. It extracts and validates tool configurations for all supported tools, converting YAML-parsed maps into strongly-typed Go structs.

Organization Rationale ¶

All tool parsing functions are grouped in this file because they:

• Share a common purpose (tool configuration parsing)
• Follow similar parsing patterns (map[string]any -> struct)
• Are called together during workflow compilation
• Provide a single source of truth for tool configuration

This follows established patterns where domain-specific parsing is grouped by functionality rather than scattered across files. See skills/developer/SKILL.md for code organization principles.

Supported Tools ¶

Built-in Tools:

• github: GitHub API and repository operations
• bash: Shell command execution
• web-fetch: HTTP content fetching
• web-search: Web search capabilities
• edit: File editing operations
• playwright: Browser automation
• serena: Serena integration
• agentic-workflows: Nested workflow execution
• cache-memory: In-workflow memory caching
• repo-memory: Repository-backed persistent memory

Configuration Tools:

• safety-prompt: Safety prompt injection
• timeout: Agent timeout configuration
• startup-timeout: Agent startup timeout

Custom Tools:

• MCP servers and other custom tool configurations

Parse Function Pattern ¶

Each parse function follows the pattern:

1. Accept any type to handle various YAML representations
2. Type-assert to expected structure (bool, string, map, array)
3. Extract and validate configuration values
4. Return strongly-typed configuration struct

This provides type safety while accommodating flexible YAML syntax.

Package workflow provides helper functions for updating GitHub entities.

This file contains shared utilities for building update entity jobs (issues, pull requests, discussions, releases). These helpers extract common patterns used across the four update entity implementations to reduce code duplication and ensure consistency in configuration parsing and job generation.

Organization Rationale ¶

These update entity helpers are grouped here because they:

• Provide generic update entity functionality used by 4 entity types
• Share common configuration patterns (target, max, field updates)
• Support two field parsing modes (key existence vs. bool value)
• Enable DRY principles for update operations

This follows the helper file conventions documented in the developer instructions. See skills/developer/SKILL.md#helper-file-conventions for details.

Key Functions ¶

Configuration Parsing:

• parseUpdateEntityConfig() - Generic update entity configuration parser
• parseUpdateEntityBase() - Parse base configuration (max, target, target-repo)
• parseUpdateEntityConfigWithFields() - Parse config with entity-specific fields
• parseUpdateEntityBoolField() - Generic boolean field parser with mode support

Field Parsing Modes:

• FieldParsingKeyExistence - Field presence indicates it can be updated (issues, discussions)
• FieldParsingBoolValue - Field's boolean value determines update permission (pull requests)

Usage Patterns ¶

The update entity helpers support two parsing strategies:

1. **Key Existence Mode** (for issues and discussions): Fields are enabled if the key exists in config, regardless of value: ```yaml update-issue: title: null # Can update title (key exists) body: null # Can update body (key exists) ```

2. **Bool Value Mode** (for pull requests): Fields are enabled based on explicit boolean values: ```yaml update-pull-request: title: true # Can update title body: false # Cannot update body ```

When to Use vs Alternatives ¶

Use these helpers when:

• Implementing update operations for GitHub entities
• Parsing update entity configurations from workflow YAML
• Building update entity jobs with consistent patterns

For create/close operations, see:

• create_*.go files for entity creation logic
• close_entity_helpers.go for entity close logic

Package workflow provides validation functions for agentic workflow compilation.

Validation Architecture ¶

The validation system for agentic workflows is organized into focused, domain-specific files to maintain clarity and single responsibility:

• validation.go: This file - package documentation only
• strict_mode_validation.go: Security and strict mode validation
• repository_features_validation.go: Repository capability detection
• schema_validation.go: GitHub Actions schema validation
• runtime_validation.go: Runtime packages, containers, expressions
• agent_validation.go: Agent files and feature support
• pip_validation.go: Python package validation
• npm_validation.go: NPM package validation
• docker_validation.go: Docker image validation
• expression_safety.go: GitHub Actions expression security
• engine_validation.go: AI engine configuration validation
• mcp_config_validation.go: MCP server configuration validation
• template_validation.go: Template structure validation

When to Add New Validation ¶

Add validation to existing domain files when:

• It fits the domain (e.g., package validation → pip_validation.go)
• It extends existing functionality

Create a new validation file when:

• It represents a distinct validation domain
• It has multiple related validation functions
• It requires its own caching or state management

Validation Patterns ¶

The validation system uses several patterns:

• Schema validation: JSON schema validation with caching
• External resource validation: Docker images, npm/pip packages
• Size limit validation: Expression sizes, file sizes
• Feature detection: Repository capabilities
• Security validation: Permission restrictions, expression safety

For detailed documentation on validation architecture, see: .github/instructions/developer.instructions.md#validation-architecture

Package workflow provides utilities for compiling agentic workflows into GitHub Actions YAML.

This file contains YAML marshaling utilities with deterministic field ordering, which is essential for GitHub Actions workflows to maintain readability and consistency.

Why Field Ordering Matters ¶

GitHub Actions workflows follow conventional field ordering that improves readability and aligns with GitHub's official documentation. While YAML and GitHub Actions don't technically require any specific field order, maintaining consistent ordering provides several benefits:

• Readability: Developers expect to see "name" first, followed by "on", then "jobs"
• Consistency: All workflows in a repository follow the same structure
• Diff-friendliness: Deterministic ordering makes git diffs more meaningful
• Maintainability: Easier to locate and update specific fields

The MapSlice Solution ¶

Go's built-in map type uses random iteration order for security reasons, which means marshaling a map[string]any to YAML produces non-deterministic field ordering. The goccy/go-yaml library provides yaml.MapSlice, which maintains insertion order:

• MapSlice is a slice of MapItem structs, each containing a Key and Value
• Fields appear in YAML in the exact order they're appended to the MapSlice
• This gives us full control over field ordering during marshaling

GitHub Actions Field Order Conventions ¶

This package follows GitHub Actions' conventional field ordering:

Workflow-level fields (top to bottom):

• name: Workflow name (always first for easy identification)
• on: Trigger events (defines when the workflow runs)
• permissions: Workflow-level permissions
• env: Workflow-level environment variables
• defaults: Default settings for all jobs
• concurrency: Concurrency control settings
• jobs: Job definitions (the main content)

Job-level fields (within each job):

• name: Job name
• runs-on: Runner specification
• permissions: Job-level permissions
• environment: Deployment environment
• if: Conditional execution
• needs: Job dependencies
• env: Job-level environment variables
• steps: Step definitions (the job's tasks)

Step-level fields (within each step):

• name: Step name
• id: Step identifier
• if: Conditional execution
• uses: Action reference (for action steps)
• run: Command to run (for shell steps)
• with: Action inputs
• env: Step-level environment variables

Event-specific and other nested fields are typically ordered alphabetically when no specific convention applies.

When to Use Ordered vs. Unordered Maps ¶

Use OrderMapFields/MarshalWithFieldOrder when:

• Creating top-level workflow structure (name, on, jobs)
• Defining job configurations
• Building step definitions
• Generating user-facing YAML that should be readable

Use regular map marshaling when:

• Field order doesn't matter for readability
• Working with internal data structures not marshaled to YAML
• Performance is critical and ordering isn't needed

References ¶

GitHub Actions workflow syntax: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

GitHub Actions best practices: https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration