goose icon indicating copy to clipboard operation
goose copied to clipboard
Published 1 week ago • verified publisher icon block

workflow: auto-update recipe-reference on release

Open dianed-square opened this issue 3 weeks ago • 3 comments

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:

  1. Extracts OpenAPI schema and Recipe struct/validation structures from two versions (old → new)
  2. Diffs both to detect field additions/removals, type changes, and validation rule changes
  3. Uses goose recipes to synthesize human-readable change documentation
  4. 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

  • [ ] Feature
  • [ ] Bug fix
  • [ ] Refactor / Code quality
  • [ ] Performance improvement
  • [ ] Documentation
  • [ ] Tests
  • [ ] Security fix
  • [x] Build / Release - New GitHub Action workflow
  • [ ] Other (specify below)

AI Assistance

  • [x] This PR was created or reviewed with AI assistance

Testing

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

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

dianed-square avatar Dec 04 '25 18:12 dianed-square

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

github-actions[bot] avatar Dec 04 '25 19:12 github-actions[bot]

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.

blackgirlbytes avatar Dec 04 '25 20:12 blackgirlbytes

@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

dianed-square avatar Dec 04 '25 22:12 dianed-square