🐛🧑‍💻 - Improve diagnostics and recovery for unsupported PR configuration schemas #635

Is there an existing issue for this?

• I have searched the existing issues.

Which actions are affected?

Pull Request (durable configuration loading and the final error boundary)

Which platforms are affected?

Linux (observed; the schema-validation path is platform-independent)

Description

When a PR contains an old Copilot configuration block without schemaVersion: 3, rejecting that state is correct. The defect is that the action reports a generic workflow failure and misleading retry advice instead of explaining the unsupported configuration and a safe recovery path.

Observed output:

Unable to read issue configuration.
GitHub Action execution failed.
Error code: workflow.failed
Retryable: Yes

The underlying error is Unsupported configuration schema. Expected 3.. In ConfigurationHandler.get, a configuration.invalid error is logged, but the original exception is rethrown. The outer Action boundary consequently falls back to workflow.failed, whose default retryability is true. Rerunning the unchanged PR cannot resolve this deterministic validation failure.

The consumer PR has a hidden copilot-configuration block containing the JSON below. Its HTML comment delimiters are omitted here because the current reader would otherwise interpret this fenced example as this issue’s own stored configuration.

{
    "branchType": "feature"
}

The missing schema version is the cause. The absence of a v3 issue-managed branch is not, by itself, an error: the same unlinked PR initializes successfully with no configuration block.

Required behavior

1. Continue rejecting present blocks with missing, malformed, old, or future/unsupported schema values. Keep the workflow/check failed until the configuration is deliberately corrected; do not migrate, infer a version, silently discard state, or convert rejection into a successful skip.
2. Preserve a typed configuration.invalid failure, retryable: false, and its correlation identity through the final Action boundary. Describe retryability as requiring configuration correction before another run can help.
3. In the failure annotation and Job Summary, identify the affected PR, distinguish a missing version from an unsupported or malformed version using bounded safe facts, state the expected version, explain the impact, and link to recovery documentation.
4. Give two explicit recovery branches: for a verified unmanaged PR with only an obsolete marker and no managed operation/state to retain, a maintainer may preserve the original body in history/a copy, remove only that obsolete block, and rerun; if the block may contain managed branch, release, hotfix, or orchestration state, stop and require maintainer review and verified restoration of supported state. Never recommend blindly adding schemaVersion: 3, deleting unknown managed state, or an automatic reset.
5. Leave the PR body and configuration untouched on validation failure. Preserve supported current-schema and absent-block behavior. Keep provider read/authorization failures distinguishable from schema validation failures.

Representative failure content

PR automation could not continue because its stored configuration is unsupported.
Cause: The configuration block has no schema version; version 3 is required.
Action: Review the PR configuration using the linked recovery guide. Remove an
obsolete block only after confirming that no managed state needs to be retained.
Retained state: The PR body and stored configuration were not changed.
Error code: configuration.invalid
Retryable without correcting configuration: No
Reference: <correlation ID>

Use existing error presentation and locale/fallback rules (including English and Spanish); keep the primary action readable in a narrow GitHub view. Raw JSON, arbitrary schema text, provider exceptions, tokens, and stack traces must not be rendered. No additional issue/PR comments or notification stream is required.

Reproducing the issue

1. Use a same-repository PR whose body contains the exact block above; the observed PR is codex/integrity-audit → develop, without an associated issue.
2. Run the generated Copilot - Pull Request workflow using vypdev/copilot@v3 by pushing a commit.
3. Observe the generic workflow.failed / Retryable: Yes output instead of an actionable configuration failure.
4. Rerun without changing the block: the failure remains.

Reproduction run · Consumer PR #144 · Repository setup commit

copilot Version

v3, resolved in the reproduction run to f7f68e699a7f7cea46e0da62388ec1a643908ae9.

Relevant Log Output

Event: pull_request, actor: efraespada, repo: vypdev/zstandard, debug: true
✅ No previous runs active. Continuing...
Unable to read issue configuration.
GitHub Action execution failed.
Impact: The workflow could not complete the requested operation.
Error code: workflow.failed
Retryable: Yes
Reference: 96fa4661-ff8e-4420-a9c7-8f2c512d16e4

Additional context and comments

Verification already performed

Local reproduction through the real configuration reader and execution-setup workflow, with provider I/O replaced by deterministic fakes:

The two existing configuration-handler and execution-setup test suites also pass: 21 tests. These controls establish the cause; they do not establish that a manually version-tagged block is safe managed state.

Implementation boundaries and documentation

Keep validation in the configuration reader, propagate the existing semantic error contract through orchestration, and render reviewed recovery content through the existing presentation/localization boundary. Do not expose raw exception prose or broaden provider permissions. No new public setting, compatibility parser, schema bump, migration path, or automatic state mutation is in scope.

Update the owning execution/error SDD and catalog evidence together with tests and the configuration, error-reference, and troubleshooting documentation when implementing. Recovery documentation must distinguish absence of a block, an obsolete unmanaged marker, and potentially valuable managed state. Schema rejection remains a fixed invariant.

References:

• Strict current-schema contract
• Configuration reader and rethrow
• Schema validation
• Semantic errors and recovery contract

Acceptance and verification budget

Minimum 15 distinct deterministic cases, with no double counting:

Acceptance: unsupported-state cases remain failed and non-retryable without correction, with the expected schema and a concrete recovery action visible; supported/absent-state cases retain their existing behavior. Tests must assert structured semantics and absence of writes, not only snapshots. Preserve repository coverage thresholds and existing architecture/error-redaction guards; run focused tests, type checking, documentation checks, and specification validation for the implementation. Record one narrow GitHub annotation/Job Summary review with a working recovery link. Pending/completed presentation follows existing behavior; partial mutation, new workflows/setup, and cancellation machinery are outside this early validation change.

This issue replaces the original compatibility/migration expectation with a diagnostic and recovery improvement. Rejection of old configurations is intentional and must remain.