Add workflow to regenerate derived files

[cmungall]

Summary

Adds a new GitHub Actions workflow (.github/workflows/regen-derived.yaml) that regenerates derived files when schema YAML files change.

Triggers:

• Push to main when any src/valuesets/schema/**/*.yaml file changes
• Manual dispatch (workflow_dispatch)

What it does:

1. Runs just gen-project and just gen-doc to regenerate derived Python datamodel, rich enums, and documentation
2. If any tracked files changed, closes any previous open PRs labeled automated-regen
3. Creates a new PR with the regenerated files for review

This replaces the need to manually run just site and commit derived file changes after schema edits.

Test plan

• Merge a schema yaml change and verify the workflow triggers
• Verify it creates a PR with the expected derived file diffs
• Verify manual dispatch works from the Actions tab

🤖 Generated with Claude Code

[claude]

Claude finished @cmungall's task —— View job

---

PR Review Complete ✅

Todo List

• Read and analyze the workflow file
• Check for code quality and best practices
• Identify potential bugs or issues
• Review performance considerations
• Assess security concerns
• Evaluate overall implementation

Review Feedback

This is a well-implemented GitHub Actions workflow with good security practices and clear logic. Here's my detailed analysis:

✅ Strengths

Security Best Practices:

• Follows least-privilege principle with minimal permissions at job level (.github/workflows/regen-derived.yaml:17-19)
• Uses secrets.GITHUB_TOKEN instead of personal access tokens
• Pinned action versions (@v4, @v5, @v6) for supply chain security

Code Quality:

• Clean, readable workflow structure
• Appropriate use of conditional execution (if: steps.changes.outputs.changed == 'true')
• Proper git configuration for automation commits (.github/workflows/regen-derived.yaml:79-80)

Logic & Error Handling:

• Smart change detection using git diff --cached --quiet (.github/workflows/regen-derived.yaml:53)
• Automatic cleanup of superseded PRs before creating new ones
• Descriptive commit messages and PR bodies

🔧 Minor Suggestions

1. Add error handling for external tool installations:

   - name: Install just
     run: uv tool install rust-just || (echo "Failed to install just" && exit 1)

2. Consider timeout for long-running jobs:

   jobs:
     regen:
       runs-on: ubuntu-latest
       timeout-minutes: 30  # Add reasonable timeout

3. Add step to verify regeneration succeeded:

   - name: Verify regeneration
     run: |
       if [ ! -d "src/valuesets/datamodel" ]; then
         echo "Regeneration failed - datamodel directory missing"
         exit 1
       fi

🎯 Performance Considerations

• Efficient use of uv caching (enable-cache: true, cache-dependency-glob: "uv.lock")
• Minimal fetch-depth: 0 is necessary for proper git operations
• Workflow only runs when schema files change, avoiding unnecessary executions

⚠️ Potential Issues

1. Race condition risk: If multiple schema changes are pushed rapidly, the workflow could create multiple competing PRs. The current PR closing logic helps but there's still a small window.

2. Branch naming collision: While unlikely due to timestamp, consider adding commit hash:

   BRANCH="auto/regen-derived-$(date +%Y%m%d-%H%M%S)-$(git rev-parse --short HEAD)"

🧪 Test Coverage

The test plan in the PR description is appropriate. Consider documenting these test scenarios:

• Push multiple schema changes in quick succession
• Manual workflow dispatch on different branches
• Scenario where regeneration produces no changes

📝 Documentation

The workflow is self-documenting with clear step names and a detailed PR body template. The inline comments (like yamllint disable) show attention to detail.

Overall Assessment

This is a solid automation workflow that follows GitHub Actions best practices. The implementation is secure, efficient, and handles edge cases well. The minor suggestions above would enhance robustness but are not blocking issues.

Recommendation: ✅ Approve - This PR is ready to merge with optional consideration of the minor enhancements suggested above.

---

[Copilot]

Pull request overview

This PR adds a GitHub Actions workflow to automatically regenerate derived files (Python datamodel, rich enums, and documentation) when schema YAML files are modified. The workflow triggers on pushes to main affecting schema files or via manual dispatch, runs the regeneration commands, and creates a PR with the changes if any files were updated.

Changes:

• New automated workflow that runs just gen-project and just gen-doc on schema changes
• Automatically closes previous regeneration PRs when superseded
• Creates labeled PRs for review of regenerated artifacts

[Copilot]

Action versions should be pinned to specific versions for reproducibility and security. The repository uses pinned versions consistently in other workflows (e.g., actions/checkout@v4.2.2, astral-sh/setup-uv@v6.4.3, actions/setup-python@v5.6.0). Update these action references to match the versions used in main.yaml and deploy-docs.yaml.

Suggested change

	uses: actions/checkout@v4
	with:
	fetch-depth: 0
	- name: Install uv
	uses: astral-sh/setup-uv@v6
	with:
	enable-cache: true
	cache-dependency-glob: "uv.lock"
	- name: Set up Python
	uses: actions/setup-python@v5
	uses: actions/checkout@v4.2.2
	with:
	fetch-depth: 0
	- name: Install uv
	uses: astral-sh/setup-uv@v6.4.3
	with:
	enable-cache: true
	cache-dependency-glob: "uv.lock"
	- name: Set up Python
	uses: actions/setup-python@v5.6.0

[Copilot]

The workflow lacks concurrency control, which could lead to race conditions if multiple schema changes are pushed to main in quick succession. Multiple workflow runs could attempt to create PRs simultaneously, or a second run could start while the first is still creating its PR. Add a concurrency group to ensure only one regeneration workflow runs at a time and cancel any in-progress runs when a new one starts.

[Copilot]

The workflow doesn't verify that the regeneration commands succeeded before attempting to create a PR. If just gen-project or just gen-doc fails, the workflow will continue and potentially create a PR with incomplete or incorrect changes. Consider adding error handling or checks to ensure the regeneration completed successfully before proceeding to create the PR.

Suggested change

	run: |
	run: |
	set -euo pipefail

[Copilot]

The workflow uses 'uv sync --group dev' while other workflows in this repository use 'uv sync --dev'. Since the pyproject.toml defines dev dependencies using dependency-groups, '--group dev' is technically correct. However, for consistency with existing workflows (main.yaml:52, deploy-docs.yaml:53), consider using '--dev' instead unless there's a specific reason to use the newer '--group' syntax.

Suggested change

	run: uv sync --group dev --no-progress
	run: uv sync --dev --no-progress

[Copilot]

The PR body has inconsistent indentation which may result in incorrectly formatted markdown. The heredoc content (lines 94-102) is indented with leading spaces while the opening 'EOF' delimiter (line 93) has no indentation. This could cause the PR description to have unexpected leading whitespace. Consider aligning the heredoc content to start at column 0 or adjusting the indentation to be consistent.

[Copilot]

The astral-sh/setup-uv action should include the python-version parameter for consistency with other workflows in this repository. In deploy-docs.yaml:36-38, the python-version is explicitly set on the setup-uv action. While the separate setup-python step will still configure Python correctly, setting it on both actions ensures consistency and clarity.

Suggested change

	cache-dependency-glob: "uv.lock"
	cache-dependency-glob: "uv.lock"
	python-version: "3.13"