workflow

func AddDetectionSuccessCheck ¶

func AddDetectionSuccessCheck(existingCondition string) string

AddDetectionSuccessCheck adds a check for detection job success to an existing condition This ensures safe output jobs only run when threat detection passes

func AddMCPFetchServerIfNeeded ¶

func AddMCPFetchServerIfNeeded(tools map[string]any, engine CodingAgentEngine) (map[string]any, []string)

AddMCPFetchServerIfNeeded adds the mcp/fetch dockerized MCP server to the tools configuration if the engine doesn't have built-in web-fetch support and web-fetch tool is requested

func BreakAtParentheses ¶

func BreakAtParentheses(expression string) []string

BreakAtParentheses attempts to break long lines at parentheses for function calls

func BreakLongExpression ¶

func BreakLongExpression(expression string) []string

BreakLongExpression breaks a long expression into multiple lines at logical points such as after || and && operators for better readability

func BuildAllowedListEnvVar ¶

func BuildAllowedListEnvVar(envVarName string, allowed []string) []string

BuildAllowedListEnvVar builds an allowed list environment variable line for safe-output jobs. envVarName should be the full env var name like "GH_AW_LABELS_ALLOWED". Always outputs the env var, even when empty (empty string means "allow all").

func BuildCloseJobEnvVars ¶

func BuildCloseJobEnvVars(prefix string, config CloseJobConfig) []string

BuildCloseJobEnvVars builds common environment variables for close operations. prefix should be like "GH_AW_CLOSE_ISSUE" or "GH_AW_CLOSE_PR". Returns a slice of environment variable lines.

func BuildListJobEnvVars ¶

func BuildListJobEnvVars(prefix string, config ListJobConfig, maxCount int) []string

BuildListJobEnvVars builds common environment variables for list-based operations. prefix should be like "GH_AW_LABELS" or "GH_AW_REVIEWERS". Returns a slice of environment variable lines.

func BuildMaxCountEnvVar ¶

func BuildMaxCountEnvVar(envVarName string, maxCount int) []string

BuildMaxCountEnvVar builds a max count environment variable line for safe-output jobs. envVarName should be the full env var name like "GH_AW_CLOSE_ISSUE_MAX_COUNT".

func BuildRequiredCategoryEnvVar ¶

func BuildRequiredCategoryEnvVar(envVarName string, requiredCategory string) []string

BuildRequiredCategoryEnvVar builds a required-category environment variable line for discussion safe-output jobs. envVarName should be the full env var name like "GH_AW_CLOSE_DISCUSSION_REQUIRED_CATEGORY". Returns an empty slice if requiredCategory is empty.

func BuildRequiredLabelsEnvVar ¶

func BuildRequiredLabelsEnvVar(envVarName string, requiredLabels []string) []string

BuildRequiredLabelsEnvVar builds a required-labels environment variable line for safe-output jobs. envVarName should be the full env var name like "GH_AW_CLOSE_ISSUE_REQUIRED_LABELS". Returns an empty slice if requiredLabels is empty.

func BuildRequiredTitlePrefixEnvVar ¶

func BuildRequiredTitlePrefixEnvVar(envVarName string, requiredTitlePrefix string) []string

BuildRequiredTitlePrefixEnvVar builds a required-title-prefix environment variable line for safe-output jobs. envVarName should be the full env var name like "GH_AW_CLOSE_ISSUE_REQUIRED_TITLE_PREFIX". Returns an empty slice if requiredTitlePrefix is empty.

func BuildTargetEnvVar ¶

func BuildTargetEnvVar(envVarName string, target string) []string

BuildTargetEnvVar builds a target environment variable line for safe-output jobs. envVarName should be the full env var name like "GH_AW_CLOSE_ISSUE_TARGET". Returns an empty slice if target is empty.

func BundleJavaScriptFromSources ¶

func BundleJavaScriptFromSources(mainContent string, sources map[string]string, basePath string) (string, error)

BundleJavaScriptFromSources bundles JavaScript from in-memory sources sources is a map where keys are file paths (e.g., "sanitize.cjs") and values are the content mainContent is the main JavaScript content that may contain require() calls basePath is the base directory path for resolving relative imports (e.g., "js")

DEPRECATED: Use BundleJavaScriptWithMode instead to specify runtime mode explicitly. This function defaults to RuntimeModeGitHubScript for backward compatibility.

Migration guide:

• For GitHub Script action (inline in YAML): use BundleJavaScriptWithMode(content, sources, basePath, RuntimeModeGitHubScript)
• For Node.js scripts (filesystem-based): use BundleJavaScriptWithMode(content, sources, basePath, RuntimeModeNodeJS)

This function will be maintained for backward compatibility but new code should use BundleJavaScriptWithMode.

func BundleJavaScriptWithMode ¶

func BundleJavaScriptWithMode(mainContent string, sources map[string]string, basePath string, mode RuntimeMode) (string, error)

BundleJavaScriptWithMode bundles JavaScript from in-memory sources with specified runtime mode sources is a map where keys are file paths (e.g., "sanitize.cjs") and values are the content mainContent is the main JavaScript content that may contain require() calls basePath is the base directory path for resolving relative imports (e.g., "js") mode specifies the target runtime environment (GitHub script action vs Node.js)

func CleanYAMLNullValues ¶

func CleanYAMLNullValues(yamlStr string) string

CleanYAMLNullValues removes " null" from YAML key-value pairs where the value is null.

GitHub Actions YAML treats workflow_dispatch: and workflow_dispatch: null identically, but the former is more concise and matches GitHub's documentation style. This function post-processes YAML strings to convert `: null` to `:` for better readability.

The function only replaces null values at the end of lines (after a colon and optional whitespace) to avoid incorrectly modifying string values that contain the word "null".

Parameters:

• yamlStr: The YAML string to process

Returns:

• The YAML string with `: null` replaced by `:`

Example:

input := "on:\n  workflow_dispatch: null\n  schedule:\n    - cron: '0 0 * * *'"
result := CleanYAMLNullValues(input)
// result: "on:\n  workflow_dispatch:\n  schedule:\n    - cron: '0 0 * * *'"

func ClearRepositoryFeaturesCache ¶

func ClearRepositoryFeaturesCache()

ClearRepositoryFeaturesCache clears the repository features cache This is useful for testing or when repository settings might have changed

func CollectSecretReferences ¶

func CollectSecretReferences(yamlContent string) []string

CollectSecretReferences extracts all secret references from the workflow YAML This scans for patterns like ${{ secrets.SECRET_NAME }} or secrets.SECRET_NAME

func ContainsCheckout ¶

func ContainsCheckout(customSteps string) bool

ContainsCheckout returns true if the given custom steps contain an actions/checkout step

func ConvertStepToYAML ¶

func ConvertStepToYAML(stepMap map[string]any) (string, error)

ConvertStepToYAML converts a step map to YAML string with proper indentation This is a shared utility function used by all engines and the compiler

func ConvertToFloat ¶

func ConvertToFloat(val any) float64

ConvertToFloat safely converts any to float64

func ConvertToInt ¶

func ConvertToInt(val any) int

ConvertToInt safely converts any to int

func EngineHasValidateSecretStep ¶

func EngineHasValidateSecretStep(engine CodingAgentEngine, data *WorkflowData) bool

EngineHasValidateSecretStep checks if the engine's installation steps include the validate-secret step. This is used to determine whether the secret_verification_result job output should be added.

The validate-secret step is only added by engines that include it in GetInstallationSteps():

• Copilot engine: Adds step when GetRequiredSecretNames returns non-empty
• Claude engine: Adds step when GetRequiredSecretNames returns non-empty
• Codex engine: Adds step when GetRequiredSecretNames returns non-empty
• Custom engine: Never adds this step (returns empty from GetInstallationSteps)

Implementation Note: This uses simple string matching which is acceptable because:

• Installation steps are generated by our code, not user input
• The "id: validate-secret" format is controlled by GenerateMultiSecretValidationStep()
• GitHubActionStep is already a string slice, not structured YAML

Parameters:

• engine: The agentic engine to check
• data: The workflow data (needed for GetInstallationSteps)

Returns:

• bool: true if the engine includes the validate-secret step, false otherwise

func EnhanceError ¶

func EnhanceError(err error, context, suggestion string) error

EnhanceError adds context to an existing error

func ExecGH ¶

func ExecGH(args ...string) *exec.Cmd

ExecGH wraps gh CLI calls and ensures proper token configuration. It uses go-gh/v2 to execute gh commands when GH_TOKEN or GITHUB_TOKEN is available, otherwise falls back to direct exec.Command for backward compatibility.

Usage:

cmd := ExecGH("api", "/user")
output, err := cmd.Output()

func ExecGHContext ¶

func ExecGHContext(ctx context.Context, args ...string) *exec.Cmd

ExecGHContext wraps gh CLI calls with context support and ensures proper token configuration. Similar to ExecGH but accepts a context for cancellation and timeout support.

Usage:

cmd := ExecGHContext(ctx, "api", "/user")
output, err := cmd.Output()

func ExecGHWithOutput ¶

func ExecGHWithOutput(args ...string) (stdout, stderr bytes.Buffer, err error)

ExecGHWithOutput executes a gh CLI command using go-gh/v2 and returns stdout, stderr, and error. This is a convenience wrapper that directly uses go-gh/v2's Exec function.

Usage:

stdout, stderr, err := ExecGHWithOutput("api", "/user")

func ExtractAgentIdentifier ¶

func ExtractAgentIdentifier(agentFile string) string

ExtractAgentIdentifier extracts the agent identifier (filename without extension) from an agent file path. This is used by the Copilot CLI which expects agent identifiers, not full paths.

Parameters:

• agentFile: The relative path to the agent file (e.g., ".github/agents/test-agent.md" or ".github/agents/test-agent.agent.md")

Returns:

• string: The agent identifier (e.g., "test-agent")

Example:

identifier := ExtractAgentIdentifier(".github/agents/my-agent.md")
// Returns: "my-agent"

identifier := ExtractAgentIdentifier(".github/agents/my-agent.agent.md")
// Returns: "my-agent"

func ExtractEnvExpressionsFromValue ¶ added in v0.43.6

func ExtractEnvExpressionsFromValue(value string) map[string]string

ExtractEnvExpressionsFromValue extracts all GitHub Actions env expressions from a string value Returns a map of environment variable names to their full env expressions Examples:

• "${{ env.SENTRY_HOST }}" -> {"SENTRY_HOST": "${{ env.SENTRY_HOST }}"}
• "${{ env.DD_SITE || 'default' }}" -> {"DD_SITE": "${{ env.DD_SITE || 'default' }}"}

func ExtractFirstMatch ¶

func ExtractFirstMatch(text, pattern string) string

ExtractFirstMatch extracts the first regex match from a string Note: This function compiles the regex on each call. For frequently-used patterns, consider pre-compiling at package level or caching the compiled regex.

func ExtractIntField ¶

func ExtractIntField(frontmatter map[string]any, key string) int

ExtractIntField is a convenience wrapper for extracting integer fields. Returns 0 if the key doesn't exist or cannot be converted.

func ExtractJSONCost ¶

func ExtractJSONCost(data map[string]any) float64

ExtractJSONCost extracts cost information from JSON data

func ExtractJSONTokenUsage ¶

func ExtractJSONTokenUsage(data map[string]any) int

ExtractJSONTokenUsage extracts token usage from JSON data

func ExtractMCPServer ¶

func ExtractMCPServer(toolName string) string

ExtractMCPServer extracts the MCP server name from a tool name

func ExtractMapField ¶

func ExtractMapField(frontmatter map[string]any, key string) map[string]any

ExtractMapField is a convenience wrapper for extracting map[string]any fields from frontmatter. This maintains backward compatibility with existing extraction patterns while preserving original types (avoiding JSON conversion which would convert all numbers to float64).

Returns an empty map if the key doesn't exist (for backward compatibility).

func ExtractSecretName ¶

func ExtractSecretName(value string) string

ExtractSecretName extracts just the secret name from a GitHub Actions expression Examples:

• "${{ secrets.DD_API_KEY }}" -> "DD_API_KEY"
• "${{ secrets.DD_SITE || 'datadoghq.com' }}" -> "DD_SITE"
• "plain value" -> ""

func ExtractSecretsFromMap ¶

func ExtractSecretsFromMap(values map[string]string) map[string]string

ExtractSecretsFromMap extracts all secrets from a map of string values Returns a map of environment variable names to their full secret expressions Example:

Input: {"DD_API_KEY": "${{ secrets.DD_API_KEY }}", "DD_SITE": "${{ secrets.DD_SITE || 'default' }}"}
Output: {"DD_API_KEY": "${{ secrets.DD_API_KEY }}", "DD_SITE": "${{ secrets.DD_SITE || 'default' }}"}

func ExtractSecretsFromValue ¶

func ExtractSecretsFromValue(value string) map[string]string

ExtractSecretsFromValue extracts all GitHub Actions secret expressions from a string value Returns a map of environment variable names to their full secret expressions Examples:

• "${{ secrets.DD_API_KEY }}" -> {"DD_API_KEY": "${{ secrets.DD_API_KEY }}"}
• "${{ secrets.DD_SITE || 'datadoghq.com' }}" -> {"DD_SITE": "${{ secrets.DD_SITE || 'datadoghq.com' }}"}
• "Bearer ${{ secrets.TOKEN }}" -> {"TOKEN": "${{ secrets.TOKEN }}"}

func ExtractStopTimeFromLockFile ¶

func ExtractStopTimeFromLockFile(lockFilePath string) string

ExtractStopTimeFromLockFile extracts the STOP_TIME value from a compiled workflow lock file

func ExtractStringField ¶

func ExtractStringField(frontmatter map[string]any, key string) string

ExtractStringField is a convenience wrapper for extracting string fields. Returns empty string if the key doesn't exist or cannot be converted.

func FilterEnvForSecrets ¶

func FilterEnvForSecrets(env map[string]string, allowedSecrets []string) map[string]string

FilterEnvForSecrets filters environment variables to only include allowed secrets This is a security measure to ensure that only necessary secrets are passed to the execution step

Parameters:

• env: Map of all environment variables
• allowedSecrets: List of secret names that are allowed to be passed

Returns:

• map[string]string: Filtered environment variables with only allowed secrets

func FinalizeToolCallsAndSequence ¶

func FinalizeToolCallsAndSequence(
	metrics *LogMetrics,
	toolCallMap map[string]*ToolCallInfo,
	currentSequence []string,
)

FinalizeToolCallsAndSequence completes the tool call and sequence finalization. Use this function when the engine extracts token usage and turns from structured result entries, rather than accumulating them during line-by-line log parsing. This is a lighter version of FinalizeToolMetrics for engines that do not need to finalize token usage and turns here.

func FinalizeToolMetrics ¶

func FinalizeToolMetrics(opts FinalizeToolMetricsOptions)

FinalizeToolMetrics completes the metric collection process by finalizing sequences, converting tool call maps to sorted slices, and optionally counting errors using patterns. This function is called by engine-specific ParseLogMetrics implementations to avoid code duplication.

func FindJavaScriptDependencies ¶

func FindJavaScriptDependencies(mainContent string, sources map[string]string, basePath string) (map[string]bool, error)

FindJavaScriptDependencies analyzes a JavaScript file and recursively finds all its dependencies without actually bundling the code. Returns a map of file paths that are required.

Parameters:

• mainContent: The JavaScript content to analyze
• sources: Map of file paths to their content
• basePath: Base directory path for resolving relative imports (e.g., "js")

Returns:

• Map of file paths (relative to basePath) that are dependencies
• Error if a required file is not found in sources

func FormatAggregatedError ¶

func FormatAggregatedError(err error, category string) error

FormatAggregatedError formats aggregated errors with a summary header Returns a formatted error with count and categorization if multiple errors exist

func FormatJavaScriptForYAML ¶

func FormatJavaScriptForYAML(script string) []string

FormatJavaScriptForYAML formats a JavaScript script with proper indentation for embedding in YAML

func FormatSecurityFindings ¶ added in v0.43.12

func FormatSecurityFindings(findings []SecurityFinding) string

FormatSecurityFindings formats a list of findings into a human-readable error message

func FormatStepWithCommandAndEnv ¶

func FormatStepWithCommandAndEnv(stepLines []string, command string, env map[string]string) []string

RenderCustomMCPToolConfigHandler is a function type that engines must provide to render their specific MCP config FormatStepWithCommandAndEnv formats a GitHub Actions step with command and environment variables. This shared function extracts the common pattern used by Copilot and Codex engines.

Parameters:

• stepLines: Existing step lines to append to (e.g., name, id, comments, timeout)
• command: The command to execute (may contain multiple lines)
• env: Map of environment variables to include in the step

Returns:

• []string: Complete step lines including run command and env section

func FormatValidationMessage ¶

func FormatValidationMessage(result *PermissionsValidationResult, strict bool) string

FormatValidationMessage formats the validation result into a human-readable message

func GenerateConcurrencyConfig ¶

func GenerateConcurrencyConfig(workflowData *WorkflowData, isCommandTrigger bool) string

GenerateConcurrencyConfig generates the concurrency configuration for a workflow based on its trigger types and characteristics.

func GenerateHeredocDelimiter ¶ added in v0.43.6

func GenerateHeredocDelimiter(name string) string

GenerateHeredocDelimiter creates a standardized heredoc delimiter with the GH_AW prefix. All heredoc delimiters in compiled lock.yml files should use this format for consistency.

The function generates delimiters in the format: GH_AW_<NAME>_EOF

Parameters:

• name: A descriptive identifier for the heredoc content (e.g., "PROMPT", "MCP_CONFIG", "TOOLS_JSON") The name should use SCREAMING_SNAKE_CASE without the _EOF suffix.

Returns a delimiter string in the format "GH_AW_<NAME>_EOF"

Example:

GenerateHeredocDelimiter("PROMPT")          // returns "GH_AW_PROMPT_EOF"
GenerateHeredocDelimiter("MCP_CONFIG")      // returns "GH_AW_MCP_CONFIG_EOF"
GenerateHeredocDelimiter("TOOLS_JSON")      // returns "GH_AW_TOOLS_JSON_EOF"
GenerateHeredocDelimiter("SRT_CONFIG")      // returns "GH_AW_SRT_CONFIG_EOF"
GenerateHeredocDelimiter("FILE_123ABC")     // returns "GH_AW_FILE_123ABC_EOF"

Usage in heredoc generation:

delimiter := GenerateHeredocDelimiter("PROMPT")
yaml.WriteString(fmt.Sprintf("cat << '%s' >> \"$GH_AW_PROMPT\"\n", delimiter))
yaml.WriteString("content here\n")
yaml.WriteString(delimiter + "\n")

func GenerateJobConcurrencyConfig ¶

func GenerateJobConcurrencyConfig(workflowData *WorkflowData) string

GenerateJobConcurrencyConfig generates the agent concurrency configuration for the agent job based on engine.concurrency field

func GenerateMaintenanceWorkflow ¶

func GenerateMaintenanceWorkflow(workflowDataList []*WorkflowData, workflowDir string, version string, actionMode ActionMode, verbose bool) error

GenerateMaintenanceWorkflow generates the agentics-maintenance.yml workflow if any workflows use the expires field for discussions or issues

func GenerateRequireScript ¶

func GenerateRequireScript(mainScriptPath string) string

GenerateRequireScript generates the JavaScript code that requires the main script from the filesystem instead of inlining the bundled code.

For GitHub Script mode, the script is wrapped in an async IIFE to support top-level await patterns used in the JavaScript files (e.g., `await main();`). The globals (github, context, core, exec, io) are automatically available in the GitHub Script execution context.

func GenerateSafeInputGoToolScriptForInspector ¶

func GenerateSafeInputGoToolScriptForInspector(toolConfig *SafeInputToolConfig) string

GenerateSafeInputGoToolScriptForInspector generates a Go script tool handler This is a public wrapper for use by the CLI inspector command

func GenerateSafeInputJavaScriptToolScriptForInspector ¶

func GenerateSafeInputJavaScriptToolScriptForInspector(toolConfig *SafeInputToolConfig) string

GenerateSafeInputJavaScriptToolScriptForInspector generates a JavaScript tool handler script This is a public wrapper for use by the CLI inspector command

func GenerateSafeInputPythonToolScriptForInspector ¶

func GenerateSafeInputPythonToolScriptForInspector(toolConfig *SafeInputToolConfig) string

GenerateSafeInputPythonToolScriptForInspector generates a Python script tool handler This is a public wrapper for use by the CLI inspector command

func GenerateSafeInputShellToolScriptForInspector ¶

func GenerateSafeInputShellToolScriptForInspector(toolConfig *SafeInputToolConfig) string

GenerateSafeInputShellToolScriptForInspector generates a shell script tool handler This is a public wrapper for use by the CLI inspector command

func GenerateSafeInputsMCPServerScriptForInspector ¶

func GenerateSafeInputsMCPServerScriptForInspector(safeInputs *SafeInputsConfig) string

GenerateSafeInputsMCPServerScriptForInspector generates the MCP server entry point script This is a public wrapper for use by the CLI inspector command

func GenerateSafeInputsToolsConfigForInspector ¶

func GenerateSafeInputsToolsConfigForInspector(safeInputs *SafeInputsConfig) string

GenerateSafeInputsToolsConfigForInspector generates the tools.json configuration for the safe-inputs MCP server This is a public wrapper for use by the CLI inspector command

func GenerateWorkflowHeader ¶

func GenerateWorkflowHeader(sourceFile string, generatedBy string, customInstructions string) string

GenerateWorkflowHeader generates the standard header comment for generated workflow files. It includes the ASCII art logo and instructions on how to regenerate the file.

Parameters:

• sourceFile: The source file path (e.g., ".md" file) that generated this workflow, or empty if not applicable
• generatedBy: Description of what generated this file (e.g., "gh-aw", "pkg/workflow/maintenance_workflow.go")
• customInstructions: Optional additional instructions to display after the standard regeneration instructions

func GenerateWriteScriptsStep ¶

func GenerateWriteScriptsStep(files []ScriptFile) []string

GenerateWriteScriptsStep generates the YAML for a step that writes all collected JavaScript files to /opt/gh-aw/scripts/. This step should be added once at the beginning of the safe_outputs job.

The generated step uses a heredoc to write each file efficiently.

func GetActionPin ¶

func GetActionPin(actionRepo string) string

GetActionPin returns the pinned action reference for a given action repository When multiple versions exist for the same repo, it returns the latest version by semver If no pin is found, it returns an empty string The returned reference includes a comment with the version tag (e.g., "repo@sha # v1")

func GetActionPinWithData ¶

func GetActionPinWithData(actionRepo, version string, data *WorkflowData) (string, error)

GetActionPinWithData returns the pinned action reference for a given action@version It tries dynamic resolution first, then falls back to hardcoded pins If resolution fails, emits a warning and returns empty string (in both strict and non-strict modes) The returned reference includes a comment with the version tag (e.g., "repo@sha # v1")

func GetActualGitHubEventName ¶

func GetActualGitHubEventName(identifier string) string

GetActualGitHubEventName returns the actual GitHub Actions event name for a given identifier This maps pull_request_comment to issue_comment since that's the actual event in GitHub Actions

func GetAllScriptFilenames ¶

func GetAllScriptFilenames() []string

GetAllScriptFilenames returns a sorted list of all .cjs filenames from the JavaScript sources. This is used by the build system to discover which files need to be embedded in custom actions. The returned list includes all .cjs files found in pkg/workflow/js/, including dependencies.

func GetAllowedDomains ¶

func GetAllowedDomains(network *NetworkPermissions) []string

GetAllowedDomains returns the allowed domains from network permissions.

Behavior based on network permissions configuration: ¶

1. No network permissions (nil): Returns default ecosystem domains for backwards compatibility.

2. Allowed list with "defaults" only: network: defaults OR network: { allowed: [defaults] } Returns default ecosystem domains.

3. Allowed list with multiple ecosystems: network: allowed: - defaults - github Processes the Allowed list, expanding all ecosystem identifiers and merging them.

4. Allowed list with custom domains: network: allowed: - example.com - python Processes the Allowed list, expanding ecosystem identifiers.

5. Empty Allowed list (deny-all): network: {} OR network: { allowed: [] } Returns empty slice (no network access).

The returned list is sorted and deduplicated.

Supported ecosystem identifiers: ¶

• "defaults": basic infrastructure (certs, JSON schema, Ubuntu, package mirrors)
• "containers": container registries (Docker, GHCR, etc.)
• "dotnet": .NET and NuGet ecosystem
• "dart": Dart/Flutter ecosystem
• "github": GitHub domains (*.githubusercontent.com, github.githubassets.com, etc.)
• "go": Go ecosystem
• "terraform": HashiCorp/Terraform
• "haskell": Haskell ecosystem
• "java": Java/Maven/Gradle
• "linux-distros": Linux distribution package repositories
• "node": Node.js/NPM/Yarn
• "perl": Perl/CPAN
• "php": PHP/Composer
• "playwright": Playwright testing framework
• "python": Python/PyPI/Conda
• "ruby": Ruby/RubyGems
• "rust": Rust/Cargo/Crates
• "swift": Swift/CocoaPods
• "github-actions": GitHub Actions blob storage domains

func GetBlockedDomains ¶

func GetBlockedDomains(network *NetworkPermissions) []string

GetBlockedDomains returns the blocked domains from network permissions Returns empty slice if no network permissions configured or no domains blocked The returned list is sorted and deduplicated Supports ecosystem identifiers (same as allowed domains)

func GetClaudeAllowedDomains ¶

func GetClaudeAllowedDomains(network *NetworkPermissions) string

GetClaudeAllowedDomains merges Claude default domains with NetworkPermissions allowed domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetClaudeAllowedDomainsWithSafeInputs ¶

func GetClaudeAllowedDomainsWithSafeInputs(network *NetworkPermissions, hasSafeInputs bool) string

GetClaudeAllowedDomainsWithSafeInputs merges Claude default domains with NetworkPermissions allowed domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag The hasSafeInputs parameter is maintained for backward compatibility but is no longer used since host.docker.internal is now in ClaudeDefaultDomains

func GetClaudeAllowedDomainsWithTools ¶

func GetClaudeAllowedDomainsWithTools(network *NetworkPermissions, tools map[string]any) string

GetClaudeAllowedDomainsWithTools merges Claude default domains with NetworkPermissions allowed domains and HTTP MCP server domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetClaudeAllowedDomainsWithToolsAndRuntimes ¶

func GetClaudeAllowedDomainsWithToolsAndRuntimes(network *NetworkPermissions, tools map[string]any, runtimes map[string]any) string

GetClaudeAllowedDomainsWithToolsAndRuntimes merges Claude default domains with NetworkPermissions, HTTP MCP server domains, and runtime ecosystem domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetCodexAllowedDomains ¶

func GetCodexAllowedDomains(network *NetworkPermissions) string

GetCodexAllowedDomains merges Codex default domains with NetworkPermissions allowed domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetCodexAllowedDomainsWithTools ¶

func GetCodexAllowedDomainsWithTools(network *NetworkPermissions, tools map[string]any) string

GetCodexAllowedDomainsWithTools merges Codex default domains with NetworkPermissions allowed domains and HTTP MCP server domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetCodexAllowedDomainsWithToolsAndRuntimes ¶

func GetCodexAllowedDomainsWithToolsAndRuntimes(network *NetworkPermissions, tools map[string]any, runtimes map[string]any) string

GetCodexAllowedDomainsWithToolsAndRuntimes merges Codex default domains with NetworkPermissions, HTTP MCP server domains, and runtime ecosystem domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetCommentEventNames ¶

func GetCommentEventNames(mappings []CommentEventMapping) []string

GetCommentEventNames returns just the event names from a list of mappings

func GetCopilotAgentPlaywrightTools ¶

func GetCopilotAgentPlaywrightTools() []any

GetCopilotAgentPlaywrightTools returns the list of playwright tools available in the copilot agent This matches the tools available in the copilot agent MCP server configuration This is a shared function used by all engines for consistent playwright tool configuration

func GetCopilotAllowedDomains ¶

func GetCopilotAllowedDomains(network *NetworkPermissions) string

GetCopilotAllowedDomains merges Copilot default domains with NetworkPermissions allowed domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetCopilotAllowedDomainsWithSafeInputs ¶

func GetCopilotAllowedDomainsWithSafeInputs(network *NetworkPermissions, hasSafeInputs bool) string

GetCopilotAllowedDomainsWithSafeInputs merges Copilot default domains with NetworkPermissions allowed domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag The hasSafeInputs parameter is maintained for backward compatibility but is no longer used since host.docker.internal is now in CopilotDefaultDomains

func GetCopilotAllowedDomainsWithTools ¶

func GetCopilotAllowedDomainsWithTools(network *NetworkPermissions, tools map[string]any) string

GetCopilotAllowedDomainsWithTools merges Copilot default domains with NetworkPermissions allowed domains and HTTP MCP server domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetCopilotAllowedDomainsWithToolsAndRuntimes ¶

func GetCopilotAllowedDomainsWithToolsAndRuntimes(network *NetworkPermissions, tools map[string]any, runtimes map[string]any) string

GetCopilotAllowedDomainsWithToolsAndRuntimes merges Copilot default domains with NetworkPermissions, HTTP MCP server domains, and runtime ecosystem domains Returns a deduplicated, sorted, comma-separated string suitable for AWF's --allow-domains flag

func GetCurrentGitTag ¶

func GetCurrentGitTag() string

GetCurrentGitTag returns the current git tag if available. Returns empty string if not on a tag.

func GetDefaultMaxForType ¶

func GetDefaultMaxForType(typeName string) int

GetDefaultMaxForType returns the default max for a type

func GetDefaultVersion ¶

func GetDefaultVersion() string

GetDefaultVersion returns the default version

func GetDomainEcosystem ¶

func GetDomainEcosystem(domain string) string

GetDomainEcosystem returns the ecosystem identifier for a given domain, or empty string if not found

func GetEnabledSafeOutputToolNames ¶

func GetEnabledSafeOutputToolNames(safeOutputs *SafeOutputsConfig) []string

GetEnabledSafeOutputToolNames returns a list of enabled safe output tool names. NOTE: Tool names should NOT be included in agent prompts. The agent should query the MCP server to discover available tools. This function is used for generating the tools.json file that the MCP server provides, and for diagnostic logging.

func GetHostedToolcachePathSetup ¶

func GetHostedToolcachePathSetup() string

GetHostedToolcachePathSetup returns a shell command that adds all runtime binaries from /opt/hostedtoolcache to PATH. This includes Node.js, Python, Go, Ruby, and other runtimes installed via actions/setup-* steps.

The hostedtoolcache directory structure is: /opt/hostedtoolcache/<tool>/<version>/<arch>/bin This function generates a command that finds all bin directories and adds them to PATH.

IMPORTANT: The command uses GH_AW_TOOL_BINS (computed by GetToolBinsSetup) which contains the specific tool paths from environment variables like GOROOT, JAVA_HOME, etc. These paths are computed on the RUNNER side and passed to the container as a literal value via --env, avoiding shell injection risks from variable expansion inside the container.

This ensures that the version configured by actions/setup-* takes precedence over other versions that may exist in hostedtoolcache. Without this, the generic `find` command returns directories in alphabetical order, causing older versions (e.g., Go 1.22.12) to shadow newer ones (e.g., Go 1.25.6) because "1.22" < "1.25" alphabetically.

This is used by all engine implementations (Copilot, Claude, Codex) to ensure consistent access to runtime tools inside the agent container.

Returns:

• string: A shell command that sets up PATH with all hostedtoolcache binaries

Example output:

export PATH="$GH_AW_TOOL_BINS$(find /opt/hostedtoolcache -maxdepth 4 -type d -name bin 2>/dev/null | tr '\n' ':')$PATH"

func GetInlinedScriptForFileMode ¶

func GetInlinedScriptForFileMode(scriptName string) (string, error)

GetInlinedScriptForFileMode gets the main script content and transforms it for inlining in the github-script action while using file mode for dependencies.

This function: 1. Adds a preamble to expose github-script globals (github, context, core, exec, io) on globalThis 2. Gets the script content from the registry 3. Transforms relative require() calls to absolute paths (e.g., './helper.cjs' -> '/opt/gh-aw/scripts/helper.cjs') 4. Patches top-level await patterns to work in the execution context

This is different from GenerateRequireScript which just generates a require() call. Inlining the main script is necessary because: - require() runs in a separate module context without the GitHub Script globals - The main script needs access to github, context, core, etc. in its top-level scope

Dependencies are still loaded from files using require() and can access the globals via globalThis (e.g., globalThis.github, globalThis.core).

func GetJavaScriptSources ¶

func GetJavaScriptSources() map[string]string

func GetLogParserBootstrap ¶

func GetLogParserBootstrap() string

func GetLogParserScript ¶

func GetLogParserScript(name string) string

func GetMCPHTTPTransportScript ¶

func GetMCPHTTPTransportScript() string

func GetMCPHandlerPythonScript ¶

func GetMCPHandlerPythonScript() string

func GetMCPHandlerShellScript ¶

func GetMCPHandlerShellScript() string

func GetMCPLoggerScript ¶

func GetMCPLoggerScript() string

func GetMCPServerCoreScript ¶

func GetMCPServerCoreScript() string

func GetMirroredEnvArgs ¶

func GetMirroredEnvArgs() []string

GetMirroredEnvArgs returns the AWF command-line arguments for mirroring environment variables from the runner into the agent container.

AWF uses the --env flag to pass environment variables in KEY=VALUE format. The output uses shell variable expansion syntax (e.g., JAVA_HOME=${JAVA_HOME}) so that the actual value is resolved at runtime from the host environment.

Example output: ["--env", "JAVA_HOME=${JAVA_HOME}", "--env", "ANDROID_HOME=${ANDROID_HOME}", ...]

This function always returns the same list of environment variables to mirror. Variables that don't exist on the host will expand to empty strings at runtime.

func GetMirroredEnvVarsList ¶

func GetMirroredEnvVarsList() []string

GetMirroredEnvVarsList returns the list of environment variables that are mirrored from the runner to the agent container.

This is useful for documentation and debugging purposes.

func GetNpmBinPathSetup ¶ added in v0.42.0

func GetNpmBinPathSetup() string

GetNpmBinPathSetup returns a simple shell command that adds hostedtoolcache bin directories to PATH. This is specifically for npm-installed CLIs (like Claude and Codex) that need to find their binaries installed via `npm install -g`.

Unlike GetHostedToolcachePathSetup(), this does NOT use GH_AW_TOOL_BINS because AWF's native chroot mode already handles tool-specific paths (GOROOT, JAVA_HOME, etc.) via AWF_HOST_PATH and the entrypoint.sh script. This function only adds the generic hostedtoolcache bin directories for npm packages.

Returns:

• string: A shell command that exports PATH with hostedtoolcache bin directories prepended

func GetReadBufferScript ¶

func GetReadBufferScript() string

func GetSafeInputsBootstrapScript ¶

func GetSafeInputsBootstrapScript() string

func GetSafeInputsConfigLoaderScript ¶

func GetSafeInputsConfigLoaderScript() string

func GetSafeInputsMCPServerHTTPScript ¶

func GetSafeInputsMCPServerHTTPScript() string

func GetSafeInputsMCPServerScript ¶

func GetSafeInputsMCPServerScript() string

func GetSafeInputsToolFactoryScript ¶

func GetSafeInputsToolFactoryScript() string

func GetSafeInputsValidationScript ¶

func GetSafeInputsValidationScript() string

func GetSafeOutputsAppendScript ¶

func GetSafeOutputsAppendScript() string

func GetSafeOutputsBootstrapScript ¶

func GetSafeOutputsBootstrapScript() string

func GetSafeOutputsConfigScript ¶

func GetSafeOutputsConfigScript() string

func GetSafeOutputsHandlersScript ¶

func GetSafeOutputsHandlersScript() string

func GetSafeOutputsMCPServerScript ¶

func GetSafeOutputsMCPServerScript() string

func GetSafeOutputsToolsJSON ¶

func GetSafeOutputsToolsJSON() string

func GetSafeOutputsToolsLoaderScript ¶

func GetSafeOutputsToolsLoaderScript() string

func GetSanitizedPATHExport ¶

func GetSanitizedPATHExport(rawPath string) string

GetSanitizedPATHExport returns a shell command that sets PATH to the given value with sanitization to remove security risks from malformed PATH entries.

The sanitization removes:

• Leading colons (e.g., ":/usr/bin" -> "/usr/bin")
• Trailing colons (e.g., "/usr/bin:" -> "/usr/bin")
• Empty elements (e.g., "/a::/b" -> "/a:/b", multiple colons collapsed to one)

Empty PATH elements are a security risk because they cause the current directory to be searched for executables, which could allow malicious code execution.

The sanitization logic is implemented in actions/setup/sh/sanitize_path.sh and is sourced at runtime from /opt/gh-aw/actions/sanitize_path.sh.

Parameters:

• rawPath: The unsanitized PATH value (may contain shell expansions like $PATH)

Returns:

• string: A shell command that sources the sanitize script to export the sanitized PATH

Example:

GetSanitizedPATHExport("$GH_AW_TOOL_BINS$PATH")
// Returns: source /opt/gh-aw/actions/sanitize_path.sh "$GH_AW_TOOL_BINS$PATH"

func GetScript ¶

func GetScript(name string) string

GetScript retrieves a bundled script from the default registry. This is a convenience function equivalent to DefaultScriptRegistry.Get(name).

DEPRECATED: Use GetScriptWithMode to specify the expected runtime mode.

func GetScriptWithMode ¶

func GetScriptWithMode(name string, mode RuntimeMode) string

GetScriptWithMode retrieves a bundled script from the default registry with mode verification. This is a convenience function equivalent to DefaultScriptRegistry.GetWithMode(name, mode).

func GetToolBinsEnvArg ¶

func GetToolBinsEnvArg() []string

GetToolBinsEnvArg returns the AWF --env argument for passing GH_AW_TOOL_BINS to the container. This should be used after GetToolBinsSetup() has been run to compute the value.

Returns:

• []string: AWF arguments ["--env", "GH_AW_TOOL_BINS=$GH_AW_TOOL_BINS"]

func GetToolBinsSetup ¶

func GetToolBinsSetup() string

GetToolBinsSetup returns a shell command that computes the GH_AW_TOOL_BINS environment variable from specific tool paths (GOROOT, JAVA_HOME, etc.).

This command should be run on the RUNNER side before invoking AWF, and the resulting GH_AW_TOOL_BINS should be passed to the container via --env. This ensures the paths are computed where they are trusted, avoiding shell injection risks.

The computed paths are prepended to PATH (via GetHostedToolcachePathSetup) before the generic find results, ensuring versions set by actions/setup-* take precedence over alphabetically-earlier versions in hostedtoolcache.

Returns:

• string: A shell command that sets GH_AW_TOOL_BINS

Example output when GOROOT=/opt/hostedtoolcache/go/1.25.6/x64 and JAVA_HOME=/opt/hostedtoolcache/Java/17.0.0/x64:

GH_AW_TOOL_BINS="/opt/hostedtoolcache/go/1.25.6/x64/bin:/opt/hostedtoolcache/Java/17.0.0/x64/bin:"

func GetValidationConfigJSON ¶

func GetValidationConfigJSON(enabledTypes []string) (string, error)

GetValidationConfigJSON returns the validation configuration as indented JSON If enabledTypes is empty or nil, returns all validation configs If enabledTypes is provided, returns only configs for the specified types

func GetVersion ¶

func GetVersion() string

GetVersion returns the current compiler version.

func GetWorkflowIDFromPath ¶

func GetWorkflowIDFromPath(markdownPath string) string

GetWorkflowIDFromPath extracts the workflow ID from a markdown file path. The workflow ID is the filename without the .md extension. Example: "/path/to/ai-moderator.md" -> "ai-moderator"

func HandleCustomMCPToolInSwitch ¶

func HandleCustomMCPToolInSwitch(
	yaml *strings.Builder,
	toolName string,
	tools map[string]any,
	isLast bool,
	renderFunc RenderCustomMCPToolConfigHandler,
) bool

HandleCustomMCPToolInSwitch processes custom MCP tools in the default case of a switch statement. This shared function extracts the common pattern used across all workflow engines.

Parameters:

• yaml: The string builder for YAML output
• toolName: The name of the tool being processed
• tools: The tools map containing tool configurations (supports both expanded and non-expanded tools)
• isLast: Whether this is the last tool in the list
• renderFunc: Engine-specific function to render the MCP configuration

Returns:

• bool: true if a custom MCP tool was handled, false otherwise

func HasMCPServers ¶

func HasMCPServers(workflowData *WorkflowData) bool

HasMCPServers checks if the workflow has any MCP servers configured

func HasSafeInputs ¶

func HasSafeInputs(safeInputs *SafeInputsConfig) bool

HasSafeInputs checks if safe-inputs are configured

func HasSafeJobsEnabled ¶

func HasSafeJobsEnabled(safeJobs map[string]*SafeJobConfig) bool

HasSafeJobsEnabled checks if any safe-jobs are enabled at the top level

func HasSafeOutputsEnabled ¶

func HasSafeOutputsEnabled(safeOutputs *SafeOutputsConfig) bool

HasSafeOutputsEnabled checks if any safe-outputs are enabled

func IsRelease ¶

func IsRelease() bool

IsRelease returns whether this binary was built as a release.

func IsReleasedVersion ¶

func IsReleasedVersion(version string) bool

IsReleasedVersion checks if a version string represents a released build. It relies on the isReleaseBuild flag set at build time via -X linker flag.

func IsSafeInputsEnabled ¶

func IsSafeInputsEnabled(safeInputs *SafeInputsConfig, workflowData *WorkflowData) bool

IsSafeInputsEnabled checks if safe-inputs are configured. Safe-inputs are enabled by default when configured in the workflow. The workflowData parameter is kept for backward compatibility but is not used.

func IsSafeInputsHTTPMode ¶

func IsSafeInputsHTTPMode(safeInputs *SafeInputsConfig) bool

IsSafeInputsHTTPMode checks if safe-inputs is configured to use HTTP mode Note: All safe-inputs configurations now use HTTP mode exclusively

func MarshalWithFieldOrder ¶

func MarshalWithFieldOrder(data map[string]any, priorityFields []string) ([]byte, error)

MarshalWithFieldOrder marshals a map to YAML with fields in a specific order.

This function ensures deterministic field ordering in the generated YAML by using yaml.MapSlice internally. Priority fields are emitted first in the order specified, then remaining fields are emitted alphabetically.

This is the primary function used throughout the workflow compiler to generate user-facing YAML for GitHub Actions workflows. It ensures workflows follow the conventional GitHub Actions field ordering, making them more readable and consistent with GitHub's documentation.

Parameters:

• data: A map of field names to values to marshal
• priorityFields: A slice of field names that should appear first, in order

Returns:

• The marshaled YAML bytes with deterministic field ordering
• An error if marshaling fails

The function uses the following YAML marshaling options:

• 2-space indentation (GitHub Actions standard)
• Literal block scalars for multiline strings (improves readability)

Example:

data := map[string]any{
    "jobs": map[string]any{...},
    "name": "My Workflow",
    "on": map[string]any{...},
    "permissions": map[string]any{...},
}
// Generate YAML with conventional field order: name, on, permissions, jobs
yaml, err := MarshalWithFieldOrder(data, []string{"name", "on", "permissions", "jobs"})
// Result:
// name: My Workflow
// on: ...
// permissions: ...
// jobs: ...

func NormalizeExpressionForComparison ¶

func NormalizeExpressionForComparison(expression string) string

NormalizeExpressionForComparison normalizes an expression by removing extra spaces and newlines This is used for comparing multiline expressions with their single-line equivalents

func OrderMapFields ¶

func OrderMapFields(data map[string]any, priorityFields []string) yaml.MapSlice

OrderMapFields converts a map to yaml.MapSlice with fields in a specific order.

yaml.MapSlice is a slice of key-value pairs that preserves insertion order during YAML marshaling. This function creates a MapSlice from a regular Go map, ensuring fields appear in a deterministic order.

The ordering strategy is:

1. Priority fields are added first, in the exact order specified
2. Remaining fields are added alphabetically

This function is useful when you need the MapSlice structure directly (e.g., for nested structures or when you need to add more items to the slice). For simple marshaling to YAML bytes, use MarshalWithFieldOrder instead.

Parameters:

• data: A map of field names to values to order
• priorityFields: Field names that should appear first, in order. If empty, all fields are sorted alphabetically.

Returns:

• A yaml.MapSlice with fields in the specified order

Example use case - Ordering job step fields:

step := map[string]any{
    "env": map[string]string{"FOO": "bar"},
    "name": "Build project",
    "run": "make build",
}
// Order step fields: name, run, env (conventional GitHub Actions order)
orderedStep := OrderMapFields(step, []string{"name", "id", "if", "uses", "run", "with", "env"})
// orderedStep will have: name, run, env (only fields that exist)

Example use case - Alphabetical ordering:

permissions := map[string]any{
    "issues": "write",
    "contents": "read",
    "pull-requests": "write",
}
// Order alphabetically by passing empty priority list
orderedPerms := OrderMapFields(permissions, []string{})
// orderedPerms will have: contents, issues, pull-requests

func ParseBoolFromConfig ¶

func ParseBoolFromConfig(m map[string]any, key string, log *logger.Logger) bool

ParseBoolFromConfig is a generic helper that extracts and validates a boolean value from a map. Returns the boolean value, or false if not present or invalid. If log is provided, it will log the extracted value for debugging.

func ParseCommandEvents ¶

func ParseCommandEvents(eventsValue any) []string

ParseCommandEvents parses the events field from command configuration Returns a list of event identifiers to enable, or nil for default (all events)

func ParseGitHubToolsets ¶

func ParseGitHubToolsets(toolsetsStr string) []string

ParseGitHubToolsets parses the toolsets string and expands "default" and "all" into their constituent toolsets. It handles comma-separated lists and deduplicates.

func ParseInputDefinitions ¶

func ParseInputDefinitions(inputsMap map[string]any) map[string]*InputDefinition

ParseInputDefinitions parses a map of input definitions from a frontmatter map. Returns a map of input name to InputDefinition.

func ParseIntFromConfig ¶

func ParseIntFromConfig(m map[string]any, key string, log *logger.Logger) int

ParseIntFromConfig is a generic helper that extracts and validates an integer value from a map. Supports int, int64, float64, and uint64 types. Returns the integer value, or 0 if not present or invalid. If log is provided, it will log the extracted value for debugging. Note: For uint64 values, returns 0 if the value would overflow int.

func ParseStringArrayFromConfig ¶

func ParseStringArrayFromConfig(m map[string]any, key string, log *logger.Logger) []string

ParseStringArrayFromConfig is a generic helper that extracts and validates a string array from a map Returns a slice of strings, or nil if not present or invalid If log is provided, it will log the extracted values for debugging

func PrettifyToolName ¶

func PrettifyToolName(toolName string) string

PrettifyToolName removes "mcp__" prefix and formats tool names nicely

func RenderConditionAsIf ¶

func RenderConditionAsIf(yaml *strings.Builder, condition ConditionNode, indent string)

RenderConditionAsIf renders a ConditionNode as an 'if' condition with proper YAML indentation

func RenderGitHubMCPDockerConfig ¶

func RenderGitHubMCPDockerConfig(yaml *strings.Builder, options GitHubMCPDockerOptions)

RenderGitHubMCPDockerConfig renders the GitHub MCP server configuration for Docker (local mode). Per MCP Gateway Specification v1.0.0 section 3.2.1, stdio-based MCP servers MUST be containerized. Uses MCP Gateway spec format: container, entrypointArgs, and env fields.

Parameters:

• yaml: The string builder for YAML output
• options: GitHub MCP Docker rendering options

func RenderGitHubMCPRemoteConfig ¶

func RenderGitHubMCPRemoteConfig(yaml *strings.Builder, options GitHubMCPRemoteOptions)

RenderGitHubMCPRemoteConfig renders the GitHub MCP server configuration for remote (hosted) mode. This shared function extracts the duplicate pattern from Claude and Copilot engines.

Parameters:

• yaml: The string builder for YAML output
• options: GitHub MCP remote rendering options

func RenderJSONMCPConfig ¶

func RenderJSONMCPConfig(
	yaml *strings.Builder,
	tools map[string]any,
	mcpTools []string,
	workflowData *WorkflowData,
	options JSONMCPConfigOptions,
) error

RenderJSONMCPConfig renders MCP configuration in JSON format with the common mcpServers structure. This shared function extracts the duplicate pattern from Claude, Copilot, and Custom engines.

Parameters:

• yaml: The string builder for YAML output
• tools: Map of tool configurations
• mcpTools: Ordered list of MCP tool names to render
• workflowData: Workflow configuration data
• options: JSON MCP config rendering options

func ReplaceSecretsWithEnvVars ¶

func ReplaceSecretsWithEnvVars(value string, secrets map[string]string) string

ReplaceSecretsWithEnvVars replaces secret expressions in a value with environment variable references Example: "${{ secrets.DD_API_KEY }}" -> "\${DD_API_KEY}" The backslash is used to escape the ${} for proper JSON rendering in Copilot configs

func ReplaceTemplateExpressionsWithEnvVars ¶ added in v0.43.6

func ReplaceTemplateExpressionsWithEnvVars(value string) string

ReplaceTemplateExpressionsWithEnvVars replaces all template expressions with environment variable references Handles: secrets.*, env.*, and github.workspace Examples:

• "${{ secrets.DD_API_KEY }}" -> "\${DD_API_KEY}"
• "${{ env.SENTRY_HOST }}" -> "\${SENTRY_HOST}"
• "${{ github.workspace }}" -> "\${GITHUB_WORKSPACE}"

func ResolveAgentFilePath ¶

func ResolveAgentFilePath(agentFile string) string

ResolveAgentFilePath returns the properly quoted agent file path with GITHUB_WORKSPACE prefix. This helper extracts the common pattern shared by Copilot, Codex, and Claude engines.

The agent file path is relative to the repository root, so we prefix it with ${GITHUB_WORKSPACE} and wrap the entire expression in double quotes to handle paths with spaces while allowing shell variable expansion.

Parameters:

• agentFile: The relative path to the agent file (e.g., ".github/agents/test-agent.md")

Returns:

• string: The double-quoted path with GITHUB_WORKSPACE prefix (e.g., "${GITHUB_WORKSPACE}/.github/agents/test-agent.md")

Example:

agentPath := ResolveAgentFilePath(".github/agents/my-agent.md")
// Returns: "${GITHUB_WORKSPACE}/.github/agents/my-agent.md"

Note: The entire path is wrapped in double quotes (not just the variable) to ensure:

1. The shellEscapeArg function recognizes it as already-quoted and doesn't add single quotes
2. Shell variable expansion works (${GITHUB_WORKSPACE} gets expanded inside double quotes)
3. Paths with spaces are properly handled

func ResolveRelativeDate ¶

func ResolveRelativeDate(dateStr string, baseTime time.Time) (string, error)

ResolveRelativeDate resolves a relative date string to an absolute timestamp suitable for use with GitHub CLI. If the date string is not relative, it returns the original string.

Returns a full ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SSZ) for precise filtering.

func ResolveSetupActionReference ¶

func ResolveSetupActionReference(actionMode ActionMode, version string, actionTag string, data *WorkflowData) string

ResolveSetupActionReference resolves the actions/setup action reference based on action mode and version. This is a standalone helper function that can be used by both Compiler methods and standalone workflow generators (like maintenance workflow) that don't have access to WorkflowData.

Parameters:

• actionMode: The action mode (dev or release)
• version: The version string to use for release mode
• actionTag: Optional override tag/SHA (takes precedence over version when in release mode)
• data: Optional WorkflowData for SHA resolution (can be nil for standalone use)

Returns:

• For dev mode: "./actions/setup" (local path)
• For release mode with data: "github/gh-aw/actions/setup@<sha> # <version>" (SHA-pinned)
• For release mode without data: "github/gh-aw/actions/setup@<version>" (tag-based, SHA resolved later)
• Falls back to local path if version is invalid in release mode

func ResolveWorkflowName ¶

func ResolveWorkflowName(workflowInput string) (string, error)

ResolveWorkflowName converts an agentic workflow ID to the GitHub Actions workflow name. It normalizes the input by removing .md and .lock.yml extensions, then finds the corresponding workflow files and extracts the actual workflow name from the lock.yml file.

The agentic workflow ID is the basename of the markdown file without the .md extension. The GitHub Actions workflow name is extracted from the "name:" field in the corresponding .lock.yml file.

Examples:

• "weekly-research" -> "Weekly Research" (from weekly-research.lock.yml name field)
• "weekly-research.md" -> "Weekly Research" (from weekly-research.lock.yml name field)
• "weekly-research.lock.yml" -> "Weekly Research" (from weekly-research.lock.yml name field)

func RewriteScriptForFileMode ¶

func RewriteScriptForFileMode(content string, currentPath string) string

RewriteScriptForFileMode rewrites a script's require statements to use absolute paths from /tmp/gh-aw/scripts/ instead of relative paths.

This transforms:

const { helper } = require('./helper.cjs');

Into:

const { helper } = require('/opt/gh-aw/scripts/helper.cjs');

func RunGH ¶

func RunGH(spinnerMessage string, args ...string) ([]byte, error)

RunGH executes a gh CLI command with a spinner and returns the stdout output. The spinner is shown in interactive terminals to provide feedback during network operations. The spinnerMessage parameter describes what operation is being performed.

Usage:

output, err := RunGH("Fetching user info...", "api", "/user")

func RunGHCombined ¶

func RunGHCombined(spinnerMessage string, args ...string) ([]byte, error)

RunGHCombined executes a gh CLI command with a spinner and returns combined stdout+stderr output. The spinner is shown in interactive terminals to provide feedback during network operations. Use this when you need to capture error messages from stderr.

Usage:

output, err := RunGHCombined("Creating repository...", "repo", "create", "myrepo")

func SanitizeIdentifier ¶

func SanitizeIdentifier(name string) string

SanitizeIdentifier sanitizes a workflow name to create a safe identifier suitable for use as a user agent string or similar context.

This is a SANITIZE function (character validity pattern). Use this when creating identifiers that must be purely alphanumeric with hyphens, with no special characters preserved. Unlike SanitizeWorkflowName which preserves dots and underscores, this function removes ALL special characters except hyphens.

The function:

• Converts to lowercase
• Replaces spaces and underscores with hyphens
• Removes non-alphanumeric characters (except hyphens)
• Consolidates multiple hyphens into a single hyphen
• Trims leading and trailing hyphens
• Returns "github-agentic-workflow" if the result would be empty

Example inputs and outputs:

SanitizeIdentifier("My Workflow")         // returns "my-workflow"
SanitizeIdentifier("test_workflow")       // returns "test-workflow"
SanitizeIdentifier("@@@")                 // returns "github-agentic-workflow" (default)
SanitizeIdentifier("Weekly v2.0")         // returns "weekly-v2-0"

This function uses the unified SanitizeName function with options configured to trim leading/trailing hyphens and return a default value for empty results. Hyphens are preserved by default in SanitizeName, not via PreserveSpecialChars.

See package documentation for guidance on when to use sanitize vs normalize patterns.

func SanitizeName ¶

func SanitizeName(name string, opts *SanitizeOptions) string

SanitizeName sanitizes a string for use as an identifier, file name, or similar context. It provides configurable behavior through the SanitizeOptions parameter.

The function performs the following transformations:

• Converts to lowercase
• Replaces common separators (colons, slashes, backslashes, spaces) with hyphens
• Replaces underscores with hyphens unless preserved in opts.PreserveSpecialChars
• Removes or replaces characters based on opts.PreserveSpecialChars
• Consolidates multiple consecutive hyphens into a single hyphen
• Optionally trims leading/trailing hyphens (controlled by opts.TrimHyphens)
• Returns opts.DefaultValue if the result is empty (controlled by opts.DefaultValue)

Example:

// Preserve dots and underscores (like SanitizeWorkflowName)
opts := &SanitizeOptions{
    PreserveSpecialChars: []rune{'.', '_'},
}
SanitizeName("My.Workflow_Name", opts) // returns "my.workflow_name"

// Trim hyphens and use default (like SanitizeIdentifier)
opts := &SanitizeOptions{
    TrimHyphens:  true,
    DefaultValue: "default-name",
}
SanitizeName("@@@", opts) // returns "default-name"

func SanitizeWorkflowIDForCacheKey ¶ added in v0.43.23

func SanitizeWorkflowIDForCacheKey(workflowID string) string

SanitizeWorkflowIDForCacheKey sanitizes a workflow ID for use in cache keys. It removes all hyphens and converts to lowercase to create a filesystem-safe identifier. Example: "Smoke-Copilot" -> "smokecopilot"

func SanitizeWorkflowName ¶

func SanitizeWorkflowName(name string) string

SanitizeWorkflowName sanitizes a workflow name for use in artifact names and file paths. It converts the name to lowercase and replaces or removes characters that are invalid in YAML artifact names or filesystem paths.

This is a SANITIZE function (character validity pattern). Use this when processing user input or workflow names that may contain invalid characters. Do NOT use this for removing file extensions - use stringutil.NormalizeWorkflowName instead.

The function performs the following transformations:

• Converts to lowercase
• Replaces colons, slashes, backslashes, and spaces with hyphens
• Replaces any remaining special characters (except dots, underscores, and hyphens) with hyphens
• Consolidates multiple consecutive hyphens into a single hyphen

Example inputs and outputs:

SanitizeWorkflowName("My Workflow: Test/Build")  // returns "my-workflow-test-build"
SanitizeWorkflowName("Weekly Research v2.0")     // returns "weekly-research-v2.0"
SanitizeWorkflowName("test_workflow")            // returns "test_workflow"

See package documentation for guidance on when to use sanitize vs normalize patterns.

func SetDefaultVersion ¶

func SetDefaultVersion(version string)

SetDefaultVersion sets the default version for compiler creation This should be called once during CLI initialization

func SetIsRelease ¶

func SetIsRelease(release bool)

SetIsRelease sets whether this binary was built as a release.

func SetVersion ¶

func SetVersion(v string)

SetVersion sets the compiler version for inclusion in generated workflow headers. Only non-dev versions are included in the generated headers.

func ShortenCommand ¶

func ShortenCommand(command string) string

ShortenCommand creates a short identifier for bash commands in workflow logs. It replaces newlines with spaces and truncates to 20 characters if needed.

This is a domain-specific function for workflow log parsing. It creates unique identifiers for bash commands by:

• Replacing newlines with spaces (bash commands can be multi-line)
• Truncating to a fixed 20 characters with "..." suffix
• Producing identifiers like "bash_echo hello world..."

For general-purpose string truncation with configurable length, use stringutil.Truncate instead.

func ShouldGeneratePRCheckoutStep ¶ added in v0.42.14

func ShouldGeneratePRCheckoutStep(data *WorkflowData) bool

ShouldGeneratePRCheckoutStep returns true if the checkout-pr step should be generated based on the workflow permissions. The step requires contents read access.

func ShouldSkipRuntimeSetup ¶

func ShouldSkipRuntimeSetup(workflowData *WorkflowData) bool

ShouldSkipRuntimeSetup checks if we should skip automatic runtime setup Deprecated: Runtime detection now smartly filters out existing runtimes instead of skipping entirely This function now always returns false for backward compatibility

func SortPermissionScopes ¶

func SortPermissionScopes(s []PermissionScope)

SortPermissionScopes sorts a slice of PermissionScope in place using Go's standard library sort

func SortStrings ¶

func SortStrings(s []string)

SortStrings sorts a slice of strings in place using Go's standard library sort

func SplitJoinedErrors ¶

func SplitJoinedErrors(err error) []error

SplitJoinedErrors splits a joined error into individual error strings

func StepsToSlice ¶

func StepsToSlice(steps []*WorkflowStep) []any

StepsToSlice converts a typed slice of WorkflowStep pointers back to []any for backward compatibility with existing YAML generation code

func SubstituteImportInputs ¶

func SubstituteImportInputs(content string, importInputs map[string]any) string

SubstituteImportInputs replaces ${{ github.aw.inputs.<key> }} expressions with the corresponding values from the importInputs map. This is called before expression extraction to inject import input values.

func TransformRequiresToAbsolutePath ¶

func TransformRequiresToAbsolutePath(content string, basePath string) string

TransformRequiresToAbsolutePath rewrites all relative require statements in content to use the specified absolute base path.

This transforms:

const { helper } = require('./helper.cjs');

Into:

const { helper } = require('/base/path/helper.cjs');

Parameters:

• content: The JavaScript content to transform
• basePath: The absolute path to use for requires (e.g., "/opt/gh-aw/safeoutputs")

func UnfenceMarkdown ¶ added in v0.42.0

func UnfenceMarkdown(content string) string

UnfenceMarkdown removes an outer code fence from markdown content if the entire content is wrapped in a markdown/md code fence. This handles cases where agents accidentally wrap the entire markdown body in a code fence.

The function detects: - Content starting with ```markdown, ```md, ~~~markdown, or ~~~md (case insensitive) - Content ending with ``` or ~~~ - The closing fence must match the opening fence type (backticks or tildes)

Returns the unfenced content if a wrapping fence is detected, otherwise returns the original content unchanged.

func UnquoteYAMLKey ¶

func UnquoteYAMLKey(yamlStr string, key string) string

UnquoteYAMLKey removes quotes from a YAML key at the start of a line.

The YAML marshaler automatically adds quotes around YAML reserved words and keywords to prevent parsing ambiguity. For example, the word "on" is a YAML boolean value, so the marshaler outputs it as "on": to distinguish it from the boolean.

However, GitHub Actions uses "on" as a top-level key for workflow triggers, and the Actions UI and documentation always show it unquoted. This function removes those quotes to match the conventional GitHub Actions syntax.

The function only replaces quoted keys at the start of a line (optionally preceded by whitespace) to avoid incorrectly unquoting string values that happen to contain the same text. For example, description: "This is about on: something" would be left unchanged.

Parameters:

• yamlStr: The YAML string to process
• key: The key to unquote (e.g., "on", "if", "true", "false")

Returns:

• The YAML string with the specified key unquoted at line starts

Example:

input := "\"on\":\n  push:\n    branches:\n      - main"
result := UnquoteYAMLKey(input, "on")
// result: "on:\n  push:\n    branches:\n      - main"

func ValidateActionSHAsInLockFile ¶

func ValidateActionSHAsInLockFile(lockFilePath string, cache *ActionCache, verbose bool) error

ValidateActionSHAsInLockFile validates action SHAs in a lock file and emits warnings

func ValidateEmbeddedResourceRequires ¶

func ValidateEmbeddedResourceRequires(sources map[string]string) error

ValidateEmbeddedResourceRequires checks that all embedded JavaScript files in the sources map have their local require() dependencies available in the sources map. This prevents bundling failures when a file requires a local module that isn't embedded.

This validation helps catch missing files in GetJavaScriptSources() at build/test time rather than at runtime when bundling fails.

Parameters:

• sources: map of file paths to their content (from GetJavaScriptSources())

Returns an error if any embedded file has local requires that reference files not in sources

func ValidateEventFilters ¶

func ValidateEventFilters(frontmatter map[string]any) error

ValidateEventFilters checks for GitHub Actions filter mutual exclusivity rules

func ValidateExpressionSafetyPublic ¶

func ValidateExpressionSafetyPublic(markdownContent string) error

ValidateExpressionSafetyPublic is a public wrapper for validateExpressionSafety that allows testing expression validation from external packages

func ValidateGitHubToolsAgainstToolsets ¶

func ValidateGitHubToolsAgainstToolsets(allowedTools []string, enabledToolsets []string) error

ValidateGitHubToolsAgainstToolsets validates that all allowed GitHub tools have their corresponding toolsets enabled in the configuration

func ValidateInList ¶

func ValidateInList(field, value string, allowedValues []string) error

ValidateInList validates that a value is in an allowed list

func ValidateLogLevel ¶

func ValidateLogLevel(level string) error

ValidateLogLevel validates that a firewall log-level value is one of the allowed enum values. Valid values are: "debug", "info", "warn", "error". Empty string is allowed as it defaults to "info" at runtime. Returns an error if the log-level is invalid.

func ValidateMCPConfigs ¶

func ValidateMCPConfigs(tools map[string]any) error

ValidateMCPConfigs validates all MCP configurations in the tools section using JSON schema

func ValidateMaxLength ¶

func ValidateMaxLength(field, value string, maxLength int) error

ValidateMaxLength validates that a field does not exceed maximum length

func ValidateMinLength ¶

func ValidateMinLength(field, value string, minLength int) error

ValidateMinLength validates that a field meets minimum length requirement

func ValidateNonNegativeInt ¶

func ValidateNonNegativeInt(field string, value int) error

ValidateNonNegativeInt validates that a value is a non-negative integer

func ValidatePositiveInt ¶

func ValidatePositiveInt(field string, value int) error

ValidatePositiveInt validates that a value is a positive integer

func ValidateRequired ¶

func ValidateRequired(field, value string) error

ValidateRequired validates that a required field is not empty

func VisitExpressionTree ¶

func VisitExpressionTree(node ConditionNode, visitor func(expr *ExpressionNode) error) error

VisitExpressionTree walks through an expression tree and calls the visitor function for each ExpressionNode (literal expression) found in the tree

func WrapErrorWithContext ¶

func WrapErrorWithContext(err error, context, suggestion string) error

WrapErrorWithContext wraps an error with additional context using fmt.Errorf %w This preserves error unwrapping while adding context

func WriteJavaScriptToYAML ¶

func WriteJavaScriptToYAML(yaml *strings.Builder, script string)

WriteJavaScriptToYAML writes a JavaScript script with proper indentation to a strings.Builder

func WriteJavaScriptToYAMLPreservingComments ¶

func WriteJavaScriptToYAMLPreservingComments(yaml *strings.Builder, script string)

WriteJavaScriptToYAMLPreservingComments writes a JavaScript script with proper indentation to a strings.Builder while preserving JSDoc and inline comments, but removing TypeScript-specific comments. Used for security-sensitive scripts like redact_secrets.

func WritePromptFileToYAML ¶

func WritePromptFileToYAML(yaml *strings.Builder, filename string, indent string)

WritePromptFileToYAML writes a shell command to cat a prompt file from /opt/gh-aw/prompts/ This replaces the previous approach of embedding prompt text in the binary.

func WritePromptTextToYAML ¶

func WritePromptTextToYAML(yaml *strings.Builder, text string, indent string)

WritePromptTextToYAML writes static prompt text to a YAML heredoc with proper indentation. Use this function for prompt text that contains NO variable placeholders or expressions. It chunks the text into groups of lines of less than MaxPromptChunkSize characters, with a maximum of MaxPromptChunks chunks. Each chunk is written as a separate heredoc to avoid GitHub Actions step size limits (21KB).

For prompt text with variable placeholders that need substitution, use WritePromptTextToYAMLWithPlaceholders instead.

func WritePromptTextToYAMLWithPlaceholders ¶

func WritePromptTextToYAMLWithPlaceholders(yaml *strings.Builder, text string, indent string)

WritePromptTextToYAMLWithPlaceholders writes prompt text with variable placeholders to a YAML heredoc with proper indentation. Use this function for prompt text containing __VAR__ placeholders that will be substituted with sed commands. The caller is responsible for adding the sed substitution commands after calling this function. It uses placeholder format (__VAR__) instead of shell variable expansion, to prevent template injection.

For static prompt text without variables, use WritePromptTextToYAML instead.

func WriteShellScriptToYAML ¶

func WriteShellScriptToYAML(yaml *strings.Builder, script string, indent string)

WriteShellScriptToYAML writes a shell script with proper indentation to a strings.Builder