docs: fix inaccuracies and add missing required flags in action.yml by kranthipoturaju · Pull Request #721 · actions/github-script

Summary

Corrects inaccuracies and fills documentation gaps in action.yml to accurately reflect the current implementation in src/main.ts and src/retry-options.ts. No behavior or code changes are included.

Changes

• result output description fixed: Previously stated the result is always "stringified with JSON.stringify", which is only true for result-encoding: json. When result-encoding: string, the output uses String(). Description now covers both paths.
• result-encoding description improved: Removed the redundant (default "json") phrase (already declared in the default: field) and replaced with the concrete JS functions used for each mode.
• user-agent description updated: The ACTIONS_ORCHESTRATION_ID environment variable is read at runtime in main.ts and silently appended to the user-agent string. This behavior was entirely undocumented in action.yml.
• required: false added to all implicitly optional inputs: debug, user-agent, previews, result-encoding, retries, and retry-exempt-status-codes were all optional but lacked the explicit flag. previews in particular had neither a default: nor required: false, making its optionality ambiguous to tooling and readers.

Motivation

action.yml is the primary machine-readable and human-readable contract for this action. Inaccurate descriptions mislead users and tooling (IDE completions, actionlint, documentation generators). The result output description was factually wrong for the string encoding path, and the undocumented ACTIONS_ORCHESTRATION_ID behavior was invisible to users trying to understand or debug user-agent strings in audit logs.

Impact

• Users: No behavioral change. All input names, defaults, and output names are unchanged—full backward compatibility is preserved.
• Tooling: actionlint and schema validators now see explicit required: false on all optional inputs, reducing false-positive warnings.
• Documentation generators: Output description now accurately describes both encoding modes.

Testing

action.yml is a metadata file with no executable logic. The change was validated by:

1. Confirming each modified field against the corresponding code path in src/main.ts (result-encoding switch, getUserAgentWithOrchestrationId, core.getInput calls).
2. Verifying no input names, defaults, or output names were altered.
3. Running git diff to confirm the diff is strictly additive to descriptions and required: false flags with no structural changes.