Refactor custom steps to support strongly-typed placement positions

[Copilot]

Overview

This PR refactors the custom steps implementation in GitHub Agentic Workflows to use strongly-typed Go structs and introduces a new object-based format that supports multiple step placement positions. The changes provide better control over when custom steps execute relative to agent execution.

Problem

Previously, custom steps were managed as YAML string fragments with only two placement options:

• steps: Runs before agent execution
• post-steps: Runs after agent execution

This limited granularity made it difficult to:

• Run steps before checkout (e.g., early validation)
• Run cleanup steps after all other steps complete
• Have clear, typed step definitions in the codebase
• Merge and manage steps from imported workflows effectively

Solution

New Step Structures

Introduced strongly-typed Go structures for managing workflow steps:

Step struct: Represents a GitHub Actions workflow step with all standard fields:

type Step struct {
    ID               string
    Name             string
    Run              string
    Uses             string
    With             map[string]any
    If               string
    Env              map[string]string
    WorkingDirectory string
    Shell            string
    TimeoutMinutes   int
    // ... other fields
}

WorkflowSteps struct: Organizes steps into four placement positions:

type WorkflowSteps struct {
    Pre       []Step  // Before checkout and runtime setup
    PreAgent  []Step  // After setup, before agent execution
    PostAgent []Step  // After agent execution
    Post      []Step  // After all other steps
}

Frontmatter Format

Users must now use an object-based format for step placement. Top-level post-steps and post-agent fields have been removed:

steps:
  pre:
    - name: Early Validation
      run: echo "Runs before checkout"
  pre-agent:
    - name: Setup Dependencies
      run: npm install
  post-agent:
    - name: Validate Results
      run: npm test
  post:
    - name: Cleanup
      run: rm -rf tmp/

Legacy array format is still supported and maps to pre-agent position:

steps:
  - name: Setup
    run: npm install

Step Execution Order

The complete workflow execution order is now:

1. Pre-activation jobs (if any)
2. Pre steps (from steps.pre)
3. Checkout repository
4. Runtime setup (Node.js, Python, etc.)
5. Pre-agent steps (from steps.pre-agent or legacy steps array)
6. Create temp directories
7. Cache restoration
8. Git configuration
9. MCP server setup
10. Prompt generation
11. Agent execution (Claude, Codex, Copilot, or Custom)
12. Error validation
13. Git patch generation (if using safe-outputs)
14. Post-agent steps (from steps.post-agent)
15. Post steps (from steps.post)

Breaking Changes

• Removed top-level post-steps field: Must now use steps: { post-agent: [...] }
• Removed top-level post-agent field: Must now use steps: { post-agent: [...] }
• Workflows using these top-level fields will need to be converted to the nested format

Changes

Core Implementation

• Added pkg/workflow/step.go with Step and WorkflowSteps types
• Added ParseStepsFromFrontmatter() to parse both legacy array and new object formats
• Updated WorkflowData struct to include ParsedSteps *WorkflowSteps
• Implemented renderStepsAtPosition() for proper YAML generation
• Updated compiler to parse, merge, and generate steps at correct positions
• Removed parsing support for top-level post-steps and post-agent fields

Schema Updates

• Extended pkg/parser/schemas/main_workflow_schema.json to support object format with named positions
• Removed top-level post-agent field definition
• Removed top-level post-steps field definition
• Maintained support for legacy array format (maps to pre-agent position)

Workflow Conversions

• Converted .github/workflows/test-post-steps.md to use nested steps: { post-agent: [...] } format

Documentation

• Added comprehensive guide in .github/instructions/github-agentic-workflows.instructions.md
• Documented all four step placement positions
• Provided examples for nested object format
• Documented step execution order and merging behavior
• Removed references to deprecated top-level fields

Testing

• Added unit tests for step parsing and merging (step_test.go)
• Added integration tests for all formats (step_integration_test.go)
• Updated all tests to use nested format
• All existing tests pass

Migration Guide

Workflows using top-level post-steps or post-agent fields must be updated:

Before (no longer supported):

steps:
  - name: Setup
    run: npm install
post-steps:
  - name: Test
    run: npm test

After (required):

steps:
  pre-agent:
    - name: Setup
      run: npm install
  post-agent:
    - name: Test
      run: npm test

Or using legacy array format for pre-agent steps:

steps:
  - name: Setup
    run: npm install
  post-agent:
    - name: Test
      run: npm test

Benefits

1. Type Safety: Steps are now strongly-typed Go structs instead of YAML strings
2. Granular Control: Four placement positions instead of two
3. Better Merging: Imported steps merge cleanly into corresponding positions
4. Cleaner Schema: Removed redundant top-level fields in favor of unified nested format
5. Flexibility: Object format supports complex step orchestration

Testing

• ✅ All unit tests pass
• ✅ All integration tests pass
• ✅ All 67 existing workflows compile successfully
• ✅ Linting and formatting checks pass
• ✅ Schema validation passes

Original prompt

Refactor that way custom steps are added to agentic workflows.

• add a strongly typed Go struct that represents a github action Step and a parser for it (look for a Step interface does not exist yet)
• redefine the front matter format to support "steps" as an array of steps or an object containing multiple named steps:

steps:
   - run: ...
   - run: ... # anotehr step

or

steps:
    pre:
        - run: ... # step happening before checkout and runtimes
    pre-agent: # steps happnening before the agent
                      # this is where "steps" goes
        - ...
    post-agent: # steps after right after the agent
        - ...
    post: # steps happnening after all steps are done
        - ...

• add strongly typed struct Go type for the "Steps" type + parser. Attached parsed data to workflowdata type.
• remove support for "post-steps" and rename it "post-agent"
• add support for merging steps from imported agentic workflows
• update schemas and tests

This change is mostly backward compatible for the agentic workflows, aside from removing "post-steps".

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pelikhan]

@copilot remove top level post-steps/post-agent field. Only keep the steps: post-agent field.
Convert agentic workflows that use post-steps to be format.

[Copilot]

@copilot remove top level post-steps/post-agent field. Only keep the steps: post-agent field.
Convert agentic workflows that use post-steps to be format.

Completed in b090a8c. Removed top-level post-agent and post-steps fields from the schema and compiler. Only the nested format steps: { post-agent: [...] } is now supported. All workflows and tests have been updated to use the nested format.