Add GitHub Actions workflow to automate ABP Studio documentation updates#24802
Add GitHub Actions workflow to automate ABP Studio documentation updates#24802m-aliozkaya merged 3 commits intodevfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds a GitHub Actions workflow to automate the updating of ABP Studio documentation when new releases are published. The workflow is triggered via repository_dispatch events and creates pull requests with AI-generated release notes.
Changes:
- Adds a new workflow file that responds to repository dispatch events with Studio release information
- Implements AI-based formatting of release notes using (intended) LLM integration
- Automates updates to release-notes.md and version-mapping.md documentation files
- Creates and auto-merges pull requests for documentation updates
| echo "FORMAT<<EOF" >> $GITHUB_OUTPUT | ||
| cat format.txt >> $GITHUB_OUTPUT | ||
| echo "EOF" >> $GITHUB_OUTPUT |
There was a problem hiding this comment.
The multiline output syntax using heredoc (EOF) should include a random delimiter to prevent potential injection attacks if the FORMAT content contains the string "EOF". GitHub recommends using a random delimiter for security. Consider using something like "EOF_${{ github.run_id }}" or follow GitHub's security best practices for multiline outputs.
| echo "FORMAT<<EOF" >> $GITHUB_OUTPUT | |
| cat format.txt >> $GITHUB_OUTPUT | |
| echo "EOF" >> $GITHUB_OUTPUT | |
| EOF_MARKER="EOF_${{ github.run_id }}" | |
| echo "FORMAT<<$EOF_MARKER" >> $GITHUB_OUTPUT | |
| cat format.txt >> $GITHUB_OUTPUT | |
| echo "$EOF_MARKER" >> $GITHUB_OUTPUT |
| --auto \ | ||
| --admin |
There was a problem hiding this comment.
Using the "--admin" flag with "gh pr merge" bypasses branch protection rules, which could allow merging without required status checks, code reviews, or other protection rules. This is a significant security and quality concern. Consider removing the "--admin" flag and ensuring proper branch protections are satisfied, or at minimum document why this bypass is necessary and acceptable for automated documentation updates.
| --auto \ | |
| --admin | |
| --auto |
| - name: Update release-notes.md | ||
| run: | | ||
| FILE="docs/en/studio/release-notes.md" | ||
| VERSION="${{ github.event.client_payload.version }}" | ||
| NAME="${{ github.event.client_payload.name }}" | ||
|
|
||
| mkdir -p docs/en/studio | ||
| touch "$FILE" | ||
|
|
||
| if ! grep -q "## Version $VERSION" "$FILE"; then | ||
| { | ||
| echo "## Version $VERSION - $NAME" | ||
| echo "" | ||
| echo "${{ steps.ai.outputs.response }}" | ||
| echo "" | ||
| echo "[Release Link](${{ github.event.client_payload.url }})" | ||
| echo "" | ||
| echo "---" | ||
| echo "" | ||
| } | cat - "$FILE" > "$FILE.new" | ||
| mv "$FILE.new" "$FILE" | ||
| else | ||
| echo "Release notes already exist" | ||
| fi |
There was a problem hiding this comment.
The workflow lacks validation that the AI response contains actual content before inserting it into the documentation. If the AI action fails or returns an empty response, this could result in malformed documentation with just the version header and release link but no actual release notes content. Add validation to check that steps.ai.outputs.response is not empty before proceeding with the file update.
| id: pr | ||
| if: steps.changes.outputs.has_changes == 'true' | ||
| env: | ||
| GH_TOKEN: ${{ secrets.BOT_SECRET }} |
There was a problem hiding this comment.
The workflow uses "secrets.BOT_SECRET" but there's no validation or documentation that this secret exists and has the required permissions. If this secret doesn't exist or lacks necessary permissions (repo access, PR creation, etc.), the PR creation and auto-merge steps will fail silently or with unclear errors. Consider adding a validation step or at least adding error handling for these operations.
| permissions: | ||
| contents: write | ||
| pull-requests: write | ||
| models: read |
There was a problem hiding this comment.
The permission "models: read" appears to be invalid. GitHub Actions does not have a standard permission called "models". Valid permissions include: actions, checks, contents, deployments, id-token, issues, discussions, packages, pages, pull-requests, repository-projects, security-events, statuses, and attestations. This line should be removed unless there's a custom permission configuration that isn't standard GitHub Actions.
| models: read |
| for key in version name notes url target_branch; do | ||
| if [ -z "${{ github.event.client_payload[key] }}" ]; then | ||
| echo "Missing payload field: $key" | ||
| exit 1 | ||
| fi | ||
| done |
There was a problem hiding this comment.
The bash variable interpolation syntax is incorrect. In bash, you cannot access nested JSON fields using the syntax "${{ github.event.client_payload[key] }}". This will not work as intended because bash doesn't evaluate GitHub Actions expressions dynamically within loops. Instead, you need to explicitly validate each field individually or use a different approach like validating them one by one with GitHub Actions expression syntax.
| for key in version name notes url target_branch; do | |
| if [ -z "${{ github.event.client_payload[key] }}" ]; then | |
| echo "Missing payload field: $key" | |
| exit 1 | |
| fi | |
| done | |
| if [ -z "${{ github.event.client_payload.version }}" ]; then | |
| echo "Missing payload field: version" | |
| exit 1 | |
| fi | |
| if [ -z "${{ github.event.client_payload.name }}" ]; then | |
| echo "Missing payload field: name" | |
| exit 1 | |
| fi | |
| if [ -z "${{ github.event.client_payload.notes }}" ]; then | |
| echo "Missing payload field: notes" | |
| exit 1 | |
| fi | |
| if [ -z "${{ github.event.client_payload.url }}" ]; then | |
| echo "Missing payload field: url" | |
| exit 1 | |
| fi | |
| if [ -z "${{ github.event.client_payload.target_branch }}" ]; then | |
| echo "Missing payload field: target_branch" | |
| exit 1 | |
| fi |
| fi | ||
|
|
||
| if ! grep -q "| $VERSION |" "$FILE"; then | ||
| echo "| $VERSION | dev |" >> "$FILE" |
There was a problem hiding this comment.
The version-mapping logic always appends "| dev |" as the ABP version without any actual mapping logic. This hardcoded value means all Studio versions will be mapped to "dev", which is likely incorrect. There should be logic to determine the correct ABP version mapping, either from the payload or through some other mechanism, rather than hardcoding "dev".
| # Checkout dev | ||
| # ----------------------------- | ||
| - uses: actions/checkout@v4 | ||
| with: | ||
| ref: dev |
There was a problem hiding this comment.
The checkout step specifies "ref: dev" hardcoded, but the PR is created against "github.event.client_payload.target_branch". This creates an inconsistency - the workflow always checks out from "dev" but creates PRs against whatever target_branch is specified in the payload. If the target_branch is not "dev", this could cause issues. The checkout should use the target_branch from the payload to ensure consistency.
| # Checkout dev | |
| # ----------------------------- | |
| - uses: actions/checkout@v4 | |
| with: | |
| ref: dev | |
| # Checkout target branch | |
| # ----------------------------- | |
| - uses: actions/checkout@v4 | |
| with: | |
| ref: ${{ github.event.client_payload.target_branch }} |
| Instructions: | ||
| - Extract only meaningful user-facing changes | ||
| - Use bullet points starting with "- " | ||
| - Be concise and professional | ||
| - Return ONLY bullet points | ||
|
|
There was a problem hiding this comment.
The AI prompt doesn't specify the expected output format explicitly enough and lacks constraints. The instruction "Return ONLY bullet points" is ambiguous - it doesn't specify whether to include a heading, what markdown style to use, or how to handle empty results. This could lead to inconsistent or malformed output. Consider providing more explicit formatting instructions and example output format.
| Instructions: | |
| - Extract only meaningful user-facing changes | |
| - Use bullet points starting with "- " | |
| - Be concise and professional | |
| - Return ONLY bullet points | |
| Instructions (strict): | |
| - Output MUST be valid GitHub-flavored Markdown. | |
| - Output MUST consist ONLY of bullet points, one change per line. | |
| - Each bullet MUST start with "- " followed immediately by the text (no other bullet style). | |
| - Do NOT include any headings, titles, introductory or closing text, or code blocks. | |
| - Do NOT include dates, versions, or links unless they are explicitly part of the raw notes. | |
| - Do NOT leave blank lines between bullets. | |
| - If there are NO meaningful user-facing changes, output exactly one bullet: "- No notable user-facing changes for this release." | |
| - Wording MUST be concise and professional. | |
| Example output format (do NOT mention "example" in your answer): | |
| - Improved startup performance for large solutions. | |
| - Added support for configuring custom templates in the project wizard. | |
| - Fixed an issue where tenant switching could fail on slow networks. |
https://github.com/volosoft/abp-studio/issues/4445