[breaking-change] Daily Breaking Change Analysis - 2026-07-06

[github-actions]

Summary

• Total Breaking Changes: 2
• Severity: HIGH
• Commits Analyzed: 1 (1b2e3b2)
• Status: ⚠️ Requires Immediate Review

Critical Breaking Changes

Two breaking schema changes were detected in the commit from the last 24 hours. Both are documented as major changesets.

Commit	File	Category	Change	Impact
1b2e3b2	pkg/parser/schemas/main_workflow_schema.json	Schema Change	imports.if field removed — conditional imports no longer accepted	Workflows using imports: - uses: ... if: ... will fail validation
1b2e3b2	pkg/parser/schemas/main_workflow_schema.json	Schema Change (Field Rename)	app: field renamed to github-app:	Workflows with top-level or nested app: auth blocks will fail validation

Full Code Diff Analysis

Breaking Change 1: Remove imports.if support

Changeset: .changeset/major-remove-imports-if.md
Category: Schema Change — Removing fields from workflow frontmatter schema
Evidence: The main_workflow_schema.json diff shows the imports array item object no longer includes an if property. The changeset confirms this is intentional.

User Impact: Any workflow frontmatter that uses if: inside an imports: entry will now fail schema validation at compile time.

Migration: Remove if: keys from imports: entries. For conditional fragment inclusion, move the condition into the workflow body using {{#if experiments.<name>}} and {{#runtime-import ...}}.

---

Breaking Change 2: Rename app: field to github-app:

Changeset: .changeset/minor-rename-app-to-github-app.md (declared as major)
Category: Schema Change — Field Rename (schema breaking per policy: renaming fields requires a major version bump)
Evidence: The main_workflow_schema.json diff shows github-app: fields added throughout; the corresponding app: key is absent from the new schema.

User Impact: Workflows using top-level app: or nested app: auth blocks will fail validation.

Migration: Replace app: with github-app: in all workflow frontmatter. An automated codemod is available: run gh aw fix.

All Commits Analyzed

Commit 1b2e3b2 — feat(no-json-stringify-error): scope-aware suggestions + detail-preserving second suggestion (#43748)

• Date: 2026-07-06
• Author: Copilot
• This is the sole commit in the repository (initial commit, all files are new additions).
• Contains 2 major changesets documenting breaking changes to schema fields.
• CLI-relevant files changed: cmd/gh-aw/main.go, pkg/cli/ (full package), pkg/parser/schemas/ (4 schema files).

Action Checklist

Complete the following items to address these breaking changes:

• Review all breaking changes detected — Verify each change is correctly categorized
• Create a changeset file in .changeset/ directory — Both changesets (major-remove-imports-if.md, minor-rename-app-to-github-app.md) already exist and specify major bump type ✅
• Add migration guidance to changeset — Migration guidance is present in both changeset files ✅
• Document breaking changes in CHANGELOG.md — Add entries under "Breaking Changes" section with user-facing descriptions
• Verify backward compatibility was considered — Confirm that alternatives to breaking were evaluated (a codemod is provided for the app: → github-app: rename)

Recommendations

1. Schema rename (app: → github-app:): Run gh aw fix to apply the provided codemod to existing workflows before upgrading.
2. Conditional imports removal: Audit all workflows for imports: entries with if: conditions and migrate to {{#runtime-import}} inside {{#if}} blocks.
3. Version bump: Both changes are marked major — the next release must be a major version bump.
4. CHANGELOG.md: Add "Breaking Changes" section entries for both changes so users are informed at upgrade time.

Reference

See scratchpad/breaking-cli-rules.md for the complete breaking change policy.

---

Once all checklist items are complete, close this issue.

⚠️ Compatibility report by Breaking Change Checker · 51.4 AIC · ⌖ 12.1 AIC · ⊞ 5.3K · ◷

• expires on Jul 8, 2026, 8:11 AM UTC-08:00