Add frontmatter formatting command by Copilot · Pull Request #59971 · github/gh-aw

Copilot · 2026-09-10T12:49:29Z

Adds gh aw format to canonicalize agentic workflow frontmatter while preserving comments and Markdown content.

Changes

Applies registered codemods before formatting.
Normalizes YAML indentation and nested mappings.
Enforces deterministic top-level field ordering.
Supports individual workflows, all workflows, and custom directories.
Adds comment-preservation, block-scalar, CLI, and roundtrip coverage.

gh aw format
gh aw format my-workflow
gh aw format --dir custom/workflows

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan

@copilot sort field by logical order then alphabetical. There is already a list of ordered fields somewhere

github-actions · 2026-09-10T13:01:04Z

🎉 Thanks for this contribution, @Copilot! The frontmatter formatting command looks great. You've added:

Clean command implementation with support for individual workflows, batch operations, and custom directories
Solid test coverage including comment preservation and block-scalar handling
Clear, documented CLI interface with practical usage examples

This aligns perfectly with the project's focus on agentic workflow tooling. The PR is ready for review by the team.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

github.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "github.com"

See Network Configuration for more information.

Generated by ✅ Contribution Check · copilot · auto · 70.6 AIC · ⌖ 5.34 AIC · ⊞ 9.4K · ◷

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-09-10T13:12:12Z

@copilot sort field by logical order then alphabetical. There is already a list of ordered fields somewhere

Implemented in 2b8663c and covered explicitly in 40290a1. Top-level fields now use constants.PriorityWorkflowFields for logical ordering, with all remaining fields sorted alphabetically.

pelikhan · 2026-09-10T13:14:20Z

@copilot add fuzz tests

Copilot

🟡 Changes recommended

--dir formatting currently includes Markdown files without YAML frontmatter (e.g. .github/workflows/shared/*.md), causing the command to fail instead of skipping non-workflow files.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new gh aw format development command to apply registered codemods and canonicalize agentic workflow YAML frontmatter (indentation + deterministic ordering) while preserving comments and the Markdown body.

Changes:

Introduces pkg/cli/format_command.go implementing the formatter (codemods + YAML normalization + ordering).
Wires the new format command into the CLI root command and command grouping.
Adds unit tests covering formatting behavior, ordering, block scalar safety, and basic CLI wiring.

File summaries

File	Description
pkg/cli/format_command.go	Implements `gh aw format`: file resolution, codemod application, frontmatter normalization + key ordering.
pkg/cli/format_command_test.go	Adds tests for codemod application, comment preservation, ordering, block scalar handling, and command wiring.
cmd/gh-aw/main.go	Registers the new `format` command and assigns it to the “development” command group.
cmd/gh-aw/command_groups_test.go	Verifies `format` is grouped under “development”.

Review details

Files reviewed: 4/4 changed files
Comments generated: 2
Review effort level: Lite

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

+	if len(workflowIDs) == 0 {
+		return getMarkdownWorkflowFiles(workflowDir)
+	}


+func TestNewFormatCommand(t *testing.T) {
+	t.Parallel()
+	cmd := NewFormatCommand()
+
+	assert.Equal(t, "format", cmd.Name())
+	assert.NotNil(t, cmd.Flags().Lookup("dir"))
+	assert.NotNil(t, cmd.ValidArgsFunction)
+}


github-actions · 2026-09-10T13:31:58Z

✅ PR Code Quality Reviewer completed the code quality review.

No additional PR write was needed after the grumpy-coder finished: its only finding duplicated an already-covered concern about bulk format behavior on non-workflow markdown.

🔎 Code quality review by PR Code Quality Reviewer

github-actions · 2026-09-10T13:32:18Z

✅ Design Decision Gate 🏗️ completed the design decision gate check. See the comment below for the result and any generated ADR draft.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

github.com
proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "github.com"
    - "proxy.golang.org"

See Network Configuration for more information.

🏗️ ADR gate enforced by Design Decision Gate 🏗️

github-actions · 2026-09-10T13:32:27Z

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer

github-actions · 2026-09-10T13:32:30Z

✅ Test Quality Sentinel completed test quality analysis.

Test Quality Sentinel skipped because pre-fetch PR data was unavailable: unable to fetch test file diff

🧪 Test quality analysis by Test Quality Sentinel

github-actions · 2026-09-10T13:32:31Z

✅ Ponytail Reviewer completed successfully!

Lean already. Ship.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

ab.chatgpt.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "ab.chatgpt.com"

See Network Configuration for more information.

Generated by Ponytail Reviewer for #59971

pelikhan · 2026-09-10T13:37:15Z

@copilot fix https://github.com/github/gh-aw/actions/runs/34481347077/job/102890724457

github-actions · 2026-09-10T13:38:18Z

🏗️ ADR Required - draft added for PR #59971

I enforced the design-decision gate for this PR because the prefetch summary shows 456 additions in default business-logic directories, which is above the 100-line threshold.

Evidence reviewed

PR title: Add frontmatter formatting command
PR body describes a new gh aw format CLI command that canonicalizes workflow frontmatter.
Diff adds pkg/cli/format_command.go and tests covering comment preservation, block scalars, round-tripping, ordering, and command registration.
No ADR link or ADR section was present in the PR body.
The most recent ADRs on branch were unrelated; no existing ADR in docs/adr/ covered this formatting-command decision.

Outcome

I generated and committed a draft ADR at:

docs/adr/59971-add-frontmatter-format-command.md

Next action for the author

Please review and refine the draft ADR so it accurately captures the intended long-term architectural decision, trade-offs, and alternatives for introducing gh aw format.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

github.com
proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "github.com"
    - "proxy.golang.org"

See Network Configuration for more information.

🏗️ ADR gate enforced by Design Decision Gate 🏗️ · pi · gpt54 · 17.1 AIC · ⌖ 10.8 AIC · ⊞ 10.1K · ◷
_{Comment /review to run again}

github-actions

Reviewed with Impeccable harden/audit guidance adapted for CLI correctness/reliability (this PR is a CLI feature, not a UI change, so most UI-specific modes don't apply).

Key finding: gh aw format writes files unconditionally on every invocation, with no dry-run-by-default / --write gate like the sibling fix command has. Given it reorders YAML keys and re-indents frontmatter across potentially the whole .github/workflows tree, this is a meaningful reliability/safety gap worth addressing before merge. A second reviewer comment already flagged that formatting all *.md files in a custom --dir (including non-workflow markdown) will fail since frontmatter is required — also valid and should be fixed.

No blocking security issues found; using COMMENT since these are correctness/UX concerns rather than security-blocking.

🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · copilot · sonnet50 · 52.7 AIC · ⌖ 13.6 AIC · ⊞ 8.4K

github-actions · 2026-09-10T13:40:13Z

+	}
+	return files, nil
+}
+


format writes changed files unconditionally with no --write/dry-run gate, unlike the sibling fix command (fix defaults to dry-run and requires --write to modify files, see pkg/cli/fix_command.go). Running gh aw format (e.g. accidentally, or in a script/CI step) will silently rewrite every matching workflow file's frontmatter with no way to preview the diff first. This is a real risk for a command that reorders YAML keys and re-indents content across an entire .github/workflows tree.

Please add a dry-run-by-default mode (print which files would change, similar to fix) with an explicit --write flag to apply changes, for consistency with fix and to avoid unexpected mass-editing of workflow files.

@copilot please address this.

github-actions

Skills-Based Review 🧠

Applied /tdd and /codebase-design on the new gh aw format command.

📋 Key Themes & Highlights

Key Themes

Error handling diverges from fix command's proven pattern: runFormatCommand returns on the first file error instead of accumulating errors/guided-errors and reporting a summary (as runFixCommand does). Combined with the existing unresolved bot comment that no-args/--dir formats all *.md files (not just workflow files), a single non-workflow or malformed file can silently abort formatting the rest of the batch.
Test coverage gap: no test locks in the desired multi-file error behavior (partial success vs. full abort), so this regression risk isn't caught by CI.
Existing unresolved review comments from Copilot already flag the --dir-without-args scope issue and a related untested failure mode — these should be resolved before merge, not just left open.

Positive Highlights

✅ Comprehensive roundtrip/idempotency tests (TestFormatWorkflowContentRoundTrips) are a great TDD practice for a formatter — running twice and asserting equality is exactly the right property to test.
✅ Careful handling of block scalars so an embedded --- inside a YAML literal block isn't mistaken for the frontmatter delimiter (TestNormalizeFrontmatterDoesNotTreatBlockScalarAsDelimiter) — good edge-case thinking.
✅ Clean reuse of the existing Codemod/GuidedError infrastructure from fix_codemods.go rather than reinventing it.

@copilot please address the review comments above.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet50 · 62 AIC · ⌖ 15.2 AIC · ⊞ 10.3K
_{Comment /matt to run again}

github-actions · 2026-09-10T13:40:21Z

+
+	codemods := GetAllCodemods()
+	for _, file := range files {
+		if err := formatWorkflowFile(file, codemods, verbose); err != nil {


[/codebase-design] Unlike runFixCommand (which processes every file, tallies successes/failures, and reports a summary even when some files error), runFormatCommand aborts on the very first file that errors and silently skips the rest. When formatting --dir or all workflows, one bad file (e.g. missing frontmatter, guided-error codemod) means no other file in the batch gets formatted, with no summary of what happened.

💡 Suggested fix

Follow the fix_command.go pattern: accumulate per-file errors (and GuidedErrors) in the loop, keep processing remaining files, and report a summary (e.g. "Formatted N of M files, X failed") instead of returning on the first failure.

var totalFormatted, totalErrors int for _, file := range files { if err := formatWorkflowFile(file, codemods, verbose); err != nil { fmt.Fprintf(os.Stderr, "%s\n", console.FormatErrorMessage(fmt.Sprintf("Error formatting %s: %v", filepath.Base(file), err))) totalErrors++ continue } totalFormatted++ }

This is especially important combined with the other reviewer's comment that --dir/no-args formats all *.md files, including non-workflow markdown — a single non-workflow file will currently abort the whole run.

@copilot please address this.

github-actions · 2026-09-10T13:40:21Z

+		"bbb:",
+		"zzz:",
+	}
+	previous := -1


[/tdd] TestRunFormatFormatsSelectedWorkflow only covers the happy path for a single file. Given the loop-abort behavior flagged above, there's no test asserting what happens when RunFormat is called with multiple WorkflowIDs and one file fails (e.g. missing frontmatter) — currently the whole batch aborts and any already-formatted files are silently left formatted with no reported summary.

💡 Suggested test

func TestRunFormatContinuesAfterFileError(t *testing.T) { t.Parallel() tempDir := t.TempDir() good := filepath.Join(tempDir, "good.md") bad := filepath.Join(tempDir, "bad.md") require.NoError(t, os.WriteFile(good, []byte("---\nengine: copilot\non:\n workflow_dispatch:\n---\n# Body"), 0o644)) require.NoError(t, os.WriteFile(bad, []byte("# no frontmatter"), 0o644)) err := RunFormat(FormatConfig{WorkflowIDs: []string{good, bad}, WorkflowDir: tempDir}) // Decide/assert desired behavior: does `good` still get formatted even though `bad` fails? require.Error(t, err) }

This red test would surface the current abort-on-first-error behavior and let the author decide (and lock in) whether it's intentional, per the accompanying [/codebase-design] comment.

@copilot please address this.

github-actions · 2026-09-10T13:40:27Z

Comment Memory

reviewed_at: 2026-09-10T13:33:35.123+00:00
review_event: REQUEST_CHANGES
top_themes:
  - workflow discovery is too shallow for repo-wide formatting
files_reviewed:
  - cmd/gh-aw/command_groups_test.go
  - cmd/gh-aw/main.go
  - pkg/cli/format_command.go
  - pkg/cli/format_command_test.go
comment_count: 1

Note

This comment is managed by comment memory.

It stores persistent context for this thread in the code block at the top of this comment.
Edit only the text inside the backtick fences; workflow metadata and the footer are regenerated automatically.

Learn more about comment memory

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 52 AIC · ⌖ 5.67 AIC · ⊞ 22.9K · ◷
_{Comment /review to run again}

github-actions

Request changes

The new formatter's file discovery is still wrong for bulk runs: it is too permissive at the top level and too shallow for the actual workflow tree, so gh aw format does not reliably normalize the set of workflow files it claims to handle.

Details

The blocking issue from this pass is that the no-arg path only scans workflowDir/*.md, which skips imported workflows under .github/workflows/shared/**. That means a repo-wide format run leaves a large chunk of the workflow corpus stale.

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 52 AIC · ⌖ 5.67 AIC · ⊞ 22.9K
_{Comment /review to run again}

github-actions · 2026-09-10T13:40:29Z

+	}
+
+	if len(workflowIDs) == 0 {
+		return getMarkdownWorkflowFiles(workflowDir)


This bulk path only scans workflowDir/*.md, so gh aw format silently skips imported workflows under .github/workflows/shared/** and never normalizes most of the workflow tree.

💡 Why this blocks merge

The command help promises that running gh aw format with no explicit workflow IDs formats all workflow markdown, but getMarkdownWorkflowFiles is a non-recursive glob. In this repo that leaves a large set of shared/imported workflows untouched, including files under shared/mcp/. I verified the current implementation formats a top-level file while leaving shared/mcp/nested.md unchanged in the same run.

Please switch discovery here to the same kind of recursive workflow traversal we use for directory expansion, then filter to actual workflow files before formatting so the bulk command covers the full workflow tree instead of just the root directory.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Done

pelikhan · 2026-09-10T13:43:43Z

@copilot reuse the same function as gh aw compile to discover the agentic workflows to format. Do not reimplement.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-09-10T13:47:01Z

@copilot add fuzz tests

Added formatter fuzz coverage in 78b64dd for idempotency, Markdown preservation, malformed input, and frontmatter delimiter round trips. The fuzz runs also exposed and fixed YAML stabilization edge cases.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-09-10T14:02:42Z

@copilot reuse the same function as gh aw compile to discover the agentic workflows to format. Do not reimplement.

Implemented in 5d093a7. Directory formatting now reuses compile's filterMarkdownFilesWithFrontmatter discovery helper, with regression coverage for mixed workflow/documentation directories.

@copilot fix https://github.com/github/gh-aw/actions/runs/34481347077/job/102890724457

Fixed in 5d093a7. The full pkg/cli suite and final impacted-test validation now pass.

github-actions · 2026-09-10T16:00:32Z

🎉 This pull request is included in a new release.

Release: v0.89.2

Add workflow frontmatter format command

46645aa

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI assigned Copilot and pelikhan Sep 10, 2026

Copilot AI changed the title ~~Add format command for workflow frontmatter~~ Add frontmatter formatting command Sep 10, 2026

Copilot finished work on behalf of pelikhan September 10, 2026 12:50

Copilot created this pull request from a session on behalf of pelikhan September 10, 2026 12:50 View session

Copilot AI requested a review from pelikhan September 10, 2026 12:50

pelikhan reviewed Sep 10, 2026

View reviewed changes

Copilot started work on behalf of pelikhan September 10, 2026 12:59 View session

github-actions Bot mentioned this pull request Sep 10, 2026

[Contribution Check Report] Contribution Check — 2026-09-10 #59836

Closed

Copilot AI and others added 2 commits September 10, 2026 13:07

Clarify logical frontmatter field ordering

2b8663c

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Make alphabetical fallback test explicit

40290a1

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan September 10, 2026 13:12

Copilot AI requested a review from pelikhan September 10, 2026 13:12

pelikhan marked this pull request as ready for review September 10, 2026 13:13

Copilot AI balanced review requested due to automatic review settings September 10, 2026 13:13

Copilot started reviewing on behalf of pelikhan September 10, 2026 13:14 View session

Copilot AI reviewed Sep 10, 2026

View reviewed changes

Copilot started work on behalf of pelikhan September 10, 2026 13:24 View session

Add ADR for format command

e16ea51

github-actions Bot reviewed Sep 10, 2026

View reviewed changes

github-actions Bot requested changes Sep 10, 2026

View reviewed changes

github-actions Bot previously requested changes Sep 10, 2026

View reviewed changes

Add formatter fuzz tests

7c96536

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Clarify formatter fuzz invariants

78b64dd

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan September 10, 2026 13:47

Copilot started work on behalf of pelikhan September 10, 2026 13:48 View session

Reuse compile workflow discovery

5d093a7

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

github-actions Bot mentioned this pull request Sep 10, 2026

[pr-sous-chef] PR Sous Chef run report #59940

Closed

Copilot finished work on behalf of pelikhan September 10, 2026 14:03

pelikhan merged commit d3ef1dc into main Sep 10, 2026
31 checks passed

pelikhan deleted the copilot/add-format-command branch September 10, 2026 14:15

github-actions Bot mentioned this pull request Sep 11, 2026

[instructions] Sync instructions with release v0.88.7 #60231

Merged

Conversation

Copilot AI commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 10, 2026

Uh oh!

Copilot AI commented Sep 10, 2026

Uh oh!

pelikhan commented Sep 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pelikhan commented Sep 10, 2026

Uh oh!

github-actions Bot commented Sep 10, 2026

Evidence reviewed

Outcome

Next action for the author

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Skills-Based Review 🧠

Key Themes

Positive Highlights

Uh oh!

github-actions Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 10, 2026

Comment Memory

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Request changes

Uh oh!

github-actions Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

pelikhan commented Sep 10, 2026

Uh oh!

Copilot AI commented Sep 10, 2026

Uh oh!

Copilot AI commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Copilot AI commented Sep 10, 2026 •

edited

Loading

github-actions Bot commented Sep 10, 2026 •

edited

Loading

github-actions Bot commented Sep 10, 2026 •

edited

Loading

github-actions Bot commented Sep 10, 2026 •

edited

Loading

github-actions Bot commented Sep 10, 2026 •

edited

Loading

github-actions Bot commented Sep 10, 2026 •

edited

Loading

Copilot AI commented Sep 10, 2026 •

edited

Loading