Add step authoring guidance to .github/aw instruction files

[Copilot]

Instruction files lacked guidance on how to implement steps:, pre-steps:, and post-steps: — leaving step type selection and shell injection prevention undocumented.

Changes

.github/aw/workflow-patterns.md — new "Step Authoring Guidance" section with explicit preference order:

• actions/github-script@v7 (preferred) — compiler handles SHA pinning; no injection risk; typed GitHub API access via github.rest.*
• Shell run: steps — user-controlled fields (issue.title, issue.body, comment.body, pull_request.title/body, head_ref) must be passed through env vars, not interpolated directly:

  # ❌ Unsafe
  run: gh issue comment ${{ github.event.issue.number }} --body "${{ github.event.issue.title }}"
  
  # ✅ Safe
  env:
    ISSUE_NUMBER: ${{ github.event.issue.number }}
    TITLE: ${{ github.event.issue.title }}
  run: gh issue comment "$ISSUE_NUMBER" --body "$TITLE"

• Python (last resort) — only when data science libraries (pandas, numpy, matplotlib) are genuinely required

.github/aw/workflow-constraints.md — shell injection added to Common Risk Areas, calling out direct ${{ github.event.* }} interpolation into run: scripts.

[github-actions]

Hey @Copilot 👋 — thanks for this addition! The new "Step Authoring Guidance" section in workflow-patterns.md is clear and practical — the explicit preference order (github-script → shell → Python) and the side-by-side safe/unsafe shell injection examples are exactly the kind of concrete, copy-pasteable guidance that prevents real mistakes in generated workflows. The companion line in workflow-constraints.md ties it neatly into the risk inventory.

One small gap to close:

• No test coverage — the diff doesn't include any test files. If the project has snapshot tests, linter rules, or schema validation for the .github/aw/ instruction files, it would be worth adding coverage to confirm the new patterns are consistent with what's enforced at runtime.

If you'd like a hand:

Check whether gh-aw has any tests or linter rules that validate patterns described in .github/aw/workflow-patterns.md — such as shell injection prevention or github-script usage preferences. If tests exist, add cases that cover the new "Step Authoring Guidance" section (preferred step type ordering, environment-variable-based injection prevention) introduced in PR #40413.

Generated by ✅ Contribution Check · 128.7 AIC · ⌖ 9.48 AIC · ⊞ 5.9K · ◷

[Copilot]

Pull request overview

This PR updates the .github/aw instruction docs to add explicit guidance for authoring steps:, pre-steps:, and post-steps: with a clear preference order and concrete shell-injection mitigation patterns.

Changes:

• Adds a new “Step Authoring Guidance” section describing when to prefer actions/github-script vs run: vs Python.
• Documents a safe pattern for using untrusted GitHub event fields in shell steps (via env: indirection).
• Adds “shell injection” to the Common Risk Areas list in workflow constraints.

Show a summary per file

File	Description
.github/aw/workflow-patterns.md	Adds step authoring guidance, including examples and shell-injection mitigation advice.
.github/aw/workflow-constraints.md	Calls out shell injection as a common risk area and recommends env-var indirection.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 4