workflow: auto-update recipe-reference on release #5988

dianed-square · 2025-12-04T18:59:23Z

Summary

This PR adds a workflow to auto-update Recipe Reference Guide on a published release. The workflow automatically detects recipe schema and validation changes between releases and creates a PR to update the Recipe Reference documentation.

Dependendent on PR #5972 for restructured recipe-reference.md file

How it works:

Extracts OpenAPI schema and Recipe struct/validation structures from two versions (old → new)
Diffs both to detect field additions/removals, type changes, and validation rule changes
Uses goose recipes to synthesize human-readable change documentation
Updates three sections in recipe-reference.md (Core Recipe Schema, Field Specifications, Validation Rules) and creates a PR if changes are detected

Changes:

.github/workflows/docs-update-recipe-ref.yml - Workflow definition
documentation/automation/ - Supporting scripts, recipes, and configuration
- scripts/ - Deterministic shell scripts for schema extraction and diffing
- recipes/ - Goose recipes for AI-powered change synthesis and documentation updates
- config/ - Serde attribute mappings and known validation file paths

Notes:

Release trigger (release: types: [published]) is commented out until reviewed; currently manual-only via workflow_dispatch
‼️ Defaults to openai/gpt-4o (same as test-finder.yml) via vars.* with fallbacks

Type of Change

AI Assistance

This PR was created or reviewed with AI assistance

Testing

Tested end-to-end in fork via workflow_dispatch (manual trigger):

Successful workflow run with PR creation

All workflow steps passed:

Schema and validation structure extraction from git tags
Change detection and diffing
AI-powered documentation synthesis (goose recipes)
PR creation with updated recipe-reference.md

Also validated the "no changes detected" path exits gracefully without creating a PR.

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1212247991125691

.github/workflows/docs-update-recipe-ref.yml

github-actions · 2025-12-04T19:02:36Z

PR Preview Action v1.6.0
Preview removed because the pull request was closed.
2025-12-15 20:13 UTC

Copilot

Pull request overview

This PR introduces an automated workflow to keep the Recipe Reference Guide synchronized with code changes. The workflow triggers on new releases (currently disabled for review) or manual dispatch, extracting schema and validation changes between versions and generating documentation updates via a hybrid approach: deterministic shell scripts for extraction/diffing, and AI-powered recipes for synthesis and documentation updates.

Key changes:

GitHub Actions workflow for automated documentation updates on releases
Shell scripts for deterministic schema extraction and change detection from Rust source code
AI recipes (goose) for synthesizing human-readable change documentation and updating markdown files
Comprehensive testing documentation and configuration files

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`.github/workflows/docs-update-recipe-ref.yml`	Workflow orchestrating the automation pipeline with manual and release triggers
`documentation/automation/README.md`	Overview of automation architecture and future projects
`documentation/automation/recipe-schema-tracking/README.md`	Detailed documentation of the recipe schema tracking system
`documentation/automation/recipe-schema-tracking/TESTING.md`	Testing guide for local and GitHub Actions execution
`documentation/automation/recipe-schema-tracking/.gitignore`	Excludes generated output files
`documentation/automation/recipe-schema-tracking/scripts/extract-schema.sh`	Extracts OpenAPI schema from git versions using Node.js
`documentation/automation/recipe-schema-tracking/scripts/extract-validation-structure.sh`	Parses Rust source files to extract struct fields and validation functions
`documentation/automation/recipe-schema-tracking/scripts/diff-validation-structures.sh`	Compares two validation structures using jq to detect changes
`documentation/automation/recipe-schema-tracking/scripts/run-pipeline.sh`	End-to-end pipeline orchestrator with progress reporting
`documentation/automation/recipe-schema-tracking/recipes/synthesize-validation-changes.yaml`	AI recipe to generate human-readable change documentation with security constraints
`documentation/automation/recipe-schema-tracking/recipes/update-recipe-reference.yaml`	AI recipe to apply changes to recipe-reference.md with strict update rules
`documentation/automation/recipe-schema-tracking/config/serde-attributes.json`	Manual mapping of Serde attributes affecting deserialization
`documentation/automation/recipe-schema-tracking/config/known-validation-files.json`	List of source files containing validation logic
`documentation/automation/recipe-schema-tracking/config/extraction-output-schema.json`	JSON schema defining extraction script output format
`documentation/automation/recipe-schema-tracking/config/validation-output-schema.json`	JSON schema defining validation rule discovery output format

documentation/automation/recipe-schema-tracking/scripts/diff-validation-structures.sh

documentation/automation/recipe-schema-tracking/recipes/update-recipe-reference.yaml

- Use environment variables instead of direct GitHub context interpolation in shell scripts to prevent potential shell injection attacks - Pin peter-evans/create-pull-request to commit SHA (v6) Resolves code scanning alerts #103, #104, #105

- Remove orphaned cleanup line referencing undefined variables in diff script - Fix missing closing asterisks in recipe yaml markdown

Copilot

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

documentation/automation/recipe-schema-tracking/scripts/run-pipeline.sh

.github/workflows/docs-update-recipe-ref.yml

Follow codebase pattern of using setup-node action rather than relying on pre-installed Node.js on GitHub runners.

blackgirlbytes · 2025-12-04T20:44:16Z

Nice. I think you said you had a fork of this already, but im just asking this to triple check.

question: did you get to try this out in a personal repo first? if not, I would say fork the repo or something and set up a github action and create a situation where this would need to trigger..because github actions can be fidgety and goose (other AI agents) don't always get them right.

- Switch from gpt-5 to gpt-4o (gpt-5 causes infinite loops in recipes) - Add 15-minute timeout to Extract and compare schemas step - Add 10-minute timeout to Update recipe-reference.md step Tested successfully in fork with gpt-4o.

Copilot

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

documentation/automation/recipe-schema-tracking/scripts/run-pipeline.sh

.github/workflows/docs-update-recipe-ref.yml

documentation/automation/recipe-schema-tracking/scripts/extract-schema.sh

- Add error handling to Steps 1b, 2, and 2b in run-pipeline.sh - Pipe JSON to node instead of embedding in command to avoid injection Tested in fork: https://github.com/dianed-square/goose/actions/runs/19945715262

dianed-square · 2025-12-04T22:54:18Z

@blackgirlbytes I did some end-to-end test runs in my fork with manual triggers though I couldn't test the published release trigger.

The workflow was validated for both the "changes detected" path (creates PR) and "no changes" path (exits gracefully). Retested again after making changes per Copilot review.

goose says to merge this workflow first and then uncomment the release trigger in a separate PR. Will need to merge the recipe-reference topic restructuring in PR #5972 first though

…erer * origin/main: (26 commits) Don't persist ephemeral extensions when resuming sessions (#5974) chore(deps): bump mdast-util-to-hast from 13.2.0 to 13.2.1 in /ui/desktop (#5939) chore(deps): bump node-forge from 1.3.1 to 1.3.2 in /documentation (#5898) Add Scorecard supply-chain security workflow (#5810) Don't show subagent tool when we're a subagent (#6125) Fix keyboard shortcut conflict for Focus Goose Window (#5809) feat(goose-cli): add feature to disable update (#5886) workflow: enable docs-update-recipe-ref (#6132) fix: filter tools in Ollama streaming when chat mode is enabled (#6118) feat(mcp): platform extension for "code mode" MCP tool calling (#6030) workflow: auto-update recipe-reference on release (#5988) Document recipe slash commands feature (#6075) docs: add GitHub Copilot device flow authentication details (#6123) Disallow subagents with no extensions (#5825) chore(deps): bump js-yaml in /documentation (#6093) feat: external goosed server (#5978) fix: Make datetime info message more explicit to prevent LLM confusion about current year (#6101) refactor: unify subagent and subrecipe tools into single tool (#5893) goose repo is too big for the issue solver workflow worker (#6099) fix: use system not developer role in db (#6098) ...

* 'main' of github.com:block/goose: (22 commits) OpenRouter & Xai streaming (#5873) fix: resolve mcp-hermit cleanup path expansion issue (#5953) feat: add goose PR reviewer workflow (#6124) perf: Avoid repeated MCP queries during streaming responses (#6138) Fix YAML serialization for recipes with special characters (#5796) Add more posthog analytics (privacy aware) (#6122) docs: add Sugar MCP server to extensions registry (#6077) Fix tokenState loading on new sessions (#6129) bump bedrock dep versions (#6090) Don't persist ephemeral extensions when resuming sessions (#5974) chore(deps): bump mdast-util-to-hast from 13.2.0 to 13.2.1 in /ui/desktop (#5939) chore(deps): bump node-forge from 1.3.1 to 1.3.2 in /documentation (#5898) Add Scorecard supply-chain security workflow (#5810) Don't show subagent tool when we're a subagent (#6125) Fix keyboard shortcut conflict for Focus Goose Window (#5809) feat(goose-cli): add feature to disable update (#5886) workflow: enable docs-update-recipe-ref (#6132) fix: filter tools in Ollama streaming when chat mode is enabled (#6118) feat(mcp): platform extension for "code mode" MCP tool calling (#6030) workflow: auto-update recipe-reference on release (#5988) ... # Conflicts: # ui/desktop/src/App.tsx # ui/desktop/src/api/sdk.gen.ts # ui/desktop/src/components/ChatInput.tsx # ui/desktop/src/components/recipes/RecipesView.tsx

Automated pipeline to detect CLI command changes between releases and update documentation. - Extract CLI structure from goose --help output - Diff between versions to detect added/removed/modified commands - AI-powered synthesis of human-readable change summaries - AI-powered documentation updates Based on recipe-schema-tracking pattern from PR block#5988.

add recipe-reference update workflow

5e18c8e

dianed-square requested a review from a team as a code owner December 4, 2025 18:59

Copilot AI review requested due to automatic review settings December 4, 2025 18:59

Copilot started reviewing on behalf of dianed-square December 4, 2025 19:00 View session

github-advanced-security bot found potential problems Dec 4, 2025

View reviewed changes

.github/workflows/docs-update-recipe-ref.yml Fixed Show fixed Hide fixed

.github/workflows/docs-update-recipe-ref.yml Fixed Show fixed Hide fixed

.github/workflows/docs-update-recipe-ref.yml Fixed Show fixed Hide fixed

Copilot finished reviewing on behalf of dianed-square December 4, 2025 19:02

Copilot AI reviewed Dec 4, 2025

View reviewed changes

documentation/automation/recipe-schema-tracking/scripts/diff-validation-structures.sh Outdated Show resolved Hide resolved

documentation/automation/recipe-schema-tracking/recipes/update-recipe-reference.yaml Outdated Show resolved Hide resolved

dianed-square added 2 commits December 4, 2025 11:50

fix: address Copilot review feedback

2f7537f

- Remove orphaned cleanup line referencing undefined variables in diff script - Fix missing closing asterisks in recipe yaml markdown

Copilot AI review requested due to automatic review settings December 4, 2025 20:11

Copilot started reviewing on behalf of dianed-square December 4, 2025 20:11 View session

Copilot finished reviewing on behalf of dianed-square December 4, 2025 20:14

Copilot AI reviewed Dec 4, 2025

View reviewed changes

documentation/automation/recipe-schema-tracking/scripts/run-pipeline.sh Show resolved Hide resolved

.github/workflows/docs-update-recipe-ref.yml Show resolved Hide resolved

.github/workflows/docs-update-recipe-ref.yml Show resolved Hide resolved

fix: add explicit Node.js setup for consistency

8cc94b7

Follow codebase pattern of using setup-node action rather than relying on pre-installed Node.js on GitHub runners.

fix: use gpt-4o and add step timeouts

e5ce142

- Switch from gpt-5 to gpt-4o (gpt-5 causes infinite loops in recipes) - Add 15-minute timeout to Extract and compare schemas step - Add 10-minute timeout to Update recipe-reference.md step Tested successfully in fork with gpt-4o.

Copilot AI review requested due to automatic review settings December 4, 2025 21:47

Copilot started reviewing on behalf of dianed-square December 4, 2025 21:48 View session

Copilot finished reviewing on behalf of dianed-square December 4, 2025 21:51

Copilot AI reviewed Dec 4, 2025

View reviewed changes

blackgirlbytes approved these changes Dec 15, 2025

View reviewed changes

dianed-square merged commit e2c3c98 into main Dec 15, 2025
19 checks passed

dianed-square deleted the automation/recipe-ref-docs branch December 15, 2025 20:11

github-actions bot mentioned this pull request Dec 16, 2025

chore(release): release version 1.17.0 (minor) #6131

Closed

dianed-square mentioned this pull request Dec 16, 2025

workflow: enable docs-update-recipe-ref #6132

Merged

10 tasks

fbalicchia pushed a commit to fbalicchia/goose that referenced this pull request Dec 16, 2025

workflow: auto-update recipe-reference on release (block#5988)

2ec708f

workflow: auto-update recipe-reference on release #5988

workflow: auto-update recipe-reference on release #5988

Uh oh!

Conversation

dianed-square commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

AI Assistance

Testing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blackgirlbytes commented Dec 4, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dianed-square commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dianed-square commented Dec 4, 2025 •

edited

Loading

github-actions bot commented Dec 4, 2025 •

edited

Loading

dianed-square commented Dec 4, 2025 •

edited

Loading