Improve runtime_setup.go error messages with context and examples

[Copilot]

Error messages in pkg/workflow/runtime_setup.go were too generic, lacking context about what custom steps are and why deduplication happens.

Changes

Enhanced error messages (2 locations):

• Parse custom steps failure (L627): Now explains that custom steps are workflow steps from frontmatter, requires valid GitHub Actions syntax, and shows example:

  failed to parse custom workflow steps from frontmatter. Custom steps must be valid GitHub Actions step syntax. Example:
  steps:
    - name: Setup
      run: echo 'hello'
    - name: Build
      run: make build
  Error: [underlying error]
  

• Marshal deduplicated steps failure (L790): Now explains deduplication removes duplicate runtime setup actions (like actions/setup-node) to avoid conflicts when automatic detection adds them:

  failed to marshal deduplicated workflow steps to YAML. Step deduplication removes duplicate runtime setup actions (like actions/setup-node) from custom steps to avoid conflicts when automatic runtime detection adds them. This optimization ensures runtime setup steps appear before custom steps. Error: [underlying error]
  

Added test coverage:

• TestRuntimeSetupErrorMessages validates parse error contains explanatory context
• TestDeduplicateErrorMessageFormat validates marshal error format

Both errors follow the pattern: what's wrong + what's expected + example + wrapped error.

Fixes #4085

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Improve runtime setup error message context</issue_title>
<issue_description>## Objective
Enhance error messages in pkg/workflow/runtime_setup.go to provide better context and actionable guidance. Currently, the file contains generic "failed to" error messages that wrap underlying errors without sufficient context.

Context

Related to #4085 - Repository Quality Improvement Report on Workflow Compilation Error Messages.

Runtime setup errors impact users working with custom workflow steps. Better error messages will help users debug configuration issues more efficiently.

Approach

Update error messages to provide better context for wrapped errors:

1. "failed to parse custom steps" → Explain what custom steps are and show example
2. "failed to marshal deduplicated steps" → Explain deduplication and its purpose
3. Add context about which part of runtime setup failed
4. Provide examples of valid runtime configurations

Even for wrapped errors, add meaningful context about what was being attempted and why it matters.

Files to Modify

• Update: pkg/workflow/runtime_setup.go
• Update: pkg/workflow/runtime_setup_test.go (add error message tests)

Example Transformations

Before:

fmt.Errorf("failed to parse: %w", err)

After:

fmt.Errorf("failed to parse custom workflow steps from frontmatter. Custom steps must be valid GitHub Actions step syntax. Example:\nsteps:\n  - name: Setup\n    run: echo 'hello'\nError: %w", err)

Before:

fmt.Errorf("failed to marshal: %w", err)

After:

fmt.Errorf("failed to marshal deduplicated workflow steps. Step deduplication removes duplicate step definitions to optimize workflow size. Error: %w", err)

Acceptance Criteria

• Wrapped errors include context about what operation was being attempted
• Error messages explain the impact or purpose of the failed operation
• Suggestions for resolution are provided where applicable
• Examples of valid configurations included for parsing errors
• Tests verify error messages contain explanatory context

Priority

Medium - Improves debugging experience for users with custom workflow steps.
Related to #4085

AI generated by Plan Command for discussion #4085</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [task] Improve runtime setup error message context #4091

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.