[github-actions] Add workflow step summaries (#148) (#173)

coisa · github-actions[bot] · web-flow · commit 02c737d66930 · 2026-04-23T14:00:52.000-03:00
* [github-actions] Add workflow step summaries (#148) * [docs] Remove duplicated review automation entries (#148) * [github-actions] Fix summary action execute bit (#148) * [github-actions] Checkout before local summary actions (#148) * [github-actions] Build reports summary markdown safely (#148) * Update wiki submodule pointer for PR #173 --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
diff --git a/.github/actions/changelog/publish-release/action.yml b/.github/actions/changelog/publish-release/action.yml
@@ -16,11 +16,20 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Publish release
+    - id: publish
+      name: Publish release
       shell: bash
       env:
         GH_TOKEN: ${{ github.token }}
         INPUT_VERSION: ${{ inputs.version }}
         INPUT_TARGET: ${{ inputs.target }}
         INPUT_NOTES_FILE: ${{ inputs.notes-file }}
       run: ${{ github.action_path }}/run.sh
+
+outputs:
+  operation:
+    description: Whether the release was created or updated.
+    value: ${{ steps.publish.outputs.operation }}
+  url:
+    description: URL of the published GitHub release.
+    value: ${{ steps.publish.outputs.url }}
diff --git a/.github/actions/changelog/publish-release/run.sh b/.github/actions/changelog/publish-release/run.sh
@@ -4,14 +4,21 @@ set -euo pipefail
 release_tag="v${INPUT_VERSION}"
 
 if gh release view "${release_tag}" --repo "${GITHUB_REPOSITORY}" >/dev/null 2>&1; then
+    operation="updated"
     gh release edit "${release_tag}" \
         --repo "${GITHUB_REPOSITORY}" \
         --title "${release_tag}" \
         --notes-file "${INPUT_NOTES_FILE}"
 else
+    operation="created"
     gh release create "${release_tag}" \
         --repo "${GITHUB_REPOSITORY}" \
         --target "${INPUT_TARGET}" \
         --title "${release_tag}" \
         --notes-file "${INPUT_NOTES_FILE}"
 fi
+
+release_url="$(gh release view "${release_tag}" --repo "${GITHUB_REPOSITORY}" --json url --jq '.url')"
+
+echo "operation=${operation}" >> "${GITHUB_OUTPUT}"
+echo "url=${release_url}" >> "${GITHUB_OUTPUT}"
diff --git a/.github/actions/github-pages/cleanup-orphaned-previews/action.yml b/.github/actions/github-pages/cleanup-orphaned-previews/action.yml
@@ -9,9 +9,21 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Cleanup orphaned previews
+    - id: cleanup
+      name: Cleanup orphaned previews
       shell: bash
       env:
         INPUT_PATH: ${{ inputs.path }}
         GH_TOKEN: ${{ github.token }}
       run: ${{ github.action_path }}/run.sh
+
+outputs:
+  deleted:
+    description: Number of deleted preview directories.
+    value: ${{ steps.cleanup.outputs.deleted }}
+  skipped:
+    description: Number of retained preview directories.
+    value: ${{ steps.cleanup.outputs.skipped }}
+  unresolved:
+    description: Number of unresolved preview directories.
+    value: ${{ steps.cleanup.outputs.unresolved }}
diff --git a/.github/actions/github-pages/cleanup-orphaned-previews/run.sh b/.github/actions/github-pages/cleanup-orphaned-previews/run.sh
@@ -46,6 +46,10 @@ done < <(find previews -mindepth 1 -maxdepth 1 -type d -name 'pr-*' | sort)
 
 echo "Preview cleanup summary: deleted=${deleted}, skipped=${skipped}, unresolved=${unresolved}."
 
+echo "deleted=${deleted}" >> "${GITHUB_OUTPUT}"
+echo "skipped=${skipped}" >> "${GITHUB_OUTPUT}"
+echo "unresolved=${unresolved}" >> "${GITHUB_OUTPUT}"
+
 touch .nojekyll
 git config user.name "github-actions[bot]"
 git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
diff --git a/.github/actions/summary/write/action.yml b/.github/actions/summary/write/action.yml
@@ -0,0 +1,16 @@
+name: Write Workflow Step Summary
+description: Append deterministic Markdown to GITHUB_STEP_SUMMARY when content is available.
+
+inputs:
+  markdown:
+    description: Markdown content to append to the workflow step summary.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Append summary
+      shell: bash
+      env:
+        INPUT_MARKDOWN: ${{ inputs.markdown }}
+      run: ${{ github.action_path }}/run.sh
diff --git a/.github/actions/summary/write/run.sh b/.github/actions/summary/write/run.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${INPUT_MARKDOWN}" ]; then
+    exit 0
+fi
+
+printf '%s\n' "${INPUT_MARKDOWN}" >> "${GITHUB_STEP_SUMMARY}"
diff --git a/.github/actions/wiki/cleanup-orphaned-previews/action.yml b/.github/actions/wiki/cleanup-orphaned-previews/action.yml
@@ -4,9 +4,21 @@ description: Delete wiki preview branches for pull requests that are no longer o
 runs:
   using: composite
   steps:
-    - name: Cleanup orphaned previews
+    - id: cleanup
+      name: Cleanup orphaned previews
       shell: bash
       env:
         GH_TOKEN: ${{ github.token }}
       working-directory: .github/wiki
       run: ${{ github.action_path }}/run.sh
+
+outputs:
+  deleted:
+    description: Number of deleted preview branches.
+    value: ${{ steps.cleanup.outputs.deleted }}
+  skipped:
+    description: Number of retained preview branches.
+    value: ${{ steps.cleanup.outputs.skipped }}
+  unresolved:
+    description: Number of unresolved preview branches.
+    value: ${{ steps.cleanup.outputs.unresolved }}
diff --git a/.github/actions/wiki/cleanup-orphaned-previews/run.sh b/.github/actions/wiki/cleanup-orphaned-previews/run.sh
@@ -3,12 +3,17 @@ set -euo pipefail
 
 git fetch origin '+refs/heads/pr-*:refs/remotes/origin/pr-*' || true
 
-git for-each-ref --format='%(refname:short)' refs/remotes/origin/pr-* | while read -r remote_branch; do
+deleted=0
+skipped=0
+unresolved=0
+
+while read -r remote_branch; do
     branch="${remote_branch#origin/}"
     pull_request_number="${branch#pr-}"
 
     if ! [[ "${pull_request_number}" =~ ^[0-9]+$ ]]; then
         echo "Skipping non-PR wiki preview branch ${branch}."
+        skipped=$((skipped + 1))
         continue
     fi
 
@@ -18,12 +23,19 @@ git for-each-ref --format='%(refname:short)' refs/remotes/origin/pr-* | while re
         CLOSED|MERGED)
             echo "Deleting wiki preview branch ${branch} for ${state} pull request #${pull_request_number}."
             git push origin --delete "${branch}" || true
+            deleted=$((deleted + 1))
             ;;
         OPEN)
             echo "Keeping wiki preview branch ${branch} for open pull request #${pull_request_number}."
+            skipped=$((skipped + 1))
             ;;
         *)
             echo "Could not resolve pull request #${pull_request_number} for wiki preview branch ${branch}. Keeping it."
+            unresolved=$((unresolved + 1))
             ;;
     esac
-done
+done < <(git for-each-ref --format='%(refname:short)' refs/remotes/origin/pr-*)
+
+echo "deleted=${deleted}" >> "${GITHUB_OUTPUT}"
+echo "skipped=${skipped}" >> "${GITHUB_OUTPUT}"
+echo "unresolved=${unresolved}" >> "${GITHUB_OUTPUT}"
diff --git a/.github/wiki b/.github/wiki
@@ -1 +1 @@
-Subproject commit e4312aab8d185e3478d1b0adbdc6d90dcfa6e042
+Subproject commit 2a1fdf63550711a077bf945b0c5d98ed7cc8b773
diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
@@ -107,6 +107,15 @@ jobs:
                   BASE_REF: ${{ github.event.pull_request.base.ref }}
               run: composer dev-tools changelog:check -- --file="${CHANGELOG_FILE}" --against="origin/${BASE_REF}"
 
+            - uses: ./.github/actions/summary/write
+              with:
+                  markdown: |
+                      ## Changelog Validation Summary
+
+                      - Changelog file: `${{ env.CHANGELOG_FILE }}`
+                      - Compared base ref: `origin/${{ github.event.pull_request.base.ref }}`
+                      - Validation result: success
+
     prepare_release_pull_request:
         name: Prepare Release Pull Request
         needs: resolve_php
@@ -181,11 +190,16 @@ jobs:
                   from-status: Merged
                   to-status: Release Prepared
 
-            - name: Summarize prepared release
-              run: |
-                  echo "Prepared release version: ${{ steps.version.outputs.value }}"
-                  echo "Pull request operation: ${{ steps.create_pr.outputs.pull-request-operation || 'none' }}"
-                  echo "Pull request URL: ${{ steps.create_pr.outputs.pull-request-url || 'not created' }}"
+            - uses: ./.github/actions/summary/write
+              with:
+                  markdown: |
+                      ## Release Preparation Summary
+
+                      - Changelog file: `${{ env.CHANGELOG_FILE }}`
+                      - Release version: `${{ steps.version.outputs.value }}`
+                      - Version source: `${{ steps.version.outputs.source }}`
+                      - Pull request operation: `${{ steps.create_pr.outputs.pull-request-operation || 'none' }}`
+                      - Pull request URL: ${{ steps.create_pr.outputs.pull-request-url || 'not created' }}
 
     publish_merged_release:
         name: Publish Merged Release
@@ -225,6 +239,7 @@ jobs:
                   version: ${{ steps.version.outputs.value }}
 
             - name: Publish GitHub release
+              id: publish_release
               uses: ./.github/actions/changelog/publish-release
               with:
                   version: ${{ steps.version.outputs.value }}
@@ -238,3 +253,13 @@ jobs:
                   from-status: Release Prepared
                   to-status: Released
                   include-current-pull-request: 'true'
+
+            - uses: ./.github/actions/summary/write
+              with:
+                  markdown: |
+                      ## Release Publication Summary
+
+                      - Changelog file: `${{ env.CHANGELOG_FILE }}`
+                      - Published tag: `v${{ steps.version.outputs.value }}`
+                      - Release operation: `${{ steps.publish_release.outputs.operation }}`
+                      - Release URL: ${{ steps.publish_release.outputs.url }}
diff --git a/.github/workflows/reports.yml b/.github/workflows/reports.yml
@@ -219,6 +219,10 @@ jobs:
         permissions:
             contents: write
             pull-requests: read
+        outputs:
+            deleted: ${{ steps.cleanup.outputs.deleted }}
+            skipped: ${{ steps.cleanup.outputs.skipped }}
+            unresolved: ${{ steps.cleanup.outputs.unresolved }}
 
         steps:
             - uses: actions/checkout@v6
@@ -230,10 +234,72 @@ jobs:
                 path: gh-pages
 
             - uses: ./.github/actions/github-pages/cleanup-orphaned-previews
+              id: cleanup
               with:
                 path: gh-pages
 
             - name: Push changes
               run: |
                 cd gh-pages
                 git push
+
+    summarize:
+        if: ${{ always() }}
+        name: Summarize Reports Workflow
+        needs:
+            - resolve_php
+            - reports
+            - verify_main_reports
+            - verify_preview_reports
+            - cleanup_preview
+            - cleanup_orphaned_previews
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+
+            - id: build_summary
+              env:
+                TRIGGER_LABEL: ${{ github.event_name }}${{ github.event.action && format(':{0}', github.event.action) || '' }}
+              run: |
+                {
+                  echo 'markdown<<EOF'
+                  echo '## Reports Workflow Summary'
+                  echo
+                  echo "- Workflow PHP version: \`${{ needs.resolve_php.outputs.php-version }}\`"
+                  echo "- PHP version source: \`${{ needs.resolve_php.outputs.php-version-source }}\`"
+                  echo "- Reports job result: \`${{ needs.reports.result }}\`"
+                  echo "- Main verification result: \`${{ needs.verify_main_reports.result }}\`"
+                  echo "- Preview verification result: \`${{ needs.verify_preview_reports.result }}\`"
+                  echo "- Closed-preview cleanup result: \`${{ needs.cleanup_preview.result }}\`"
+                  echo "- Orphan cleanup result: \`${{ needs.cleanup_orphaned_previews.result }}\`"
+                  echo "- Trigger: \`${TRIGGER_LABEL}\`"
+
+                  if [ "${{ github.event_name }}" = "push" ] || { [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.cleanup-previews }}" != "true" ]; }; then
+                    echo "- Docs: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+                    echo "- Coverage: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/coverage/"
+                    echo "- Metrics: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/metrics/"
+                    echo "- Deployment verification: \`${{ needs.verify_main_reports.result }}\`"
+                  fi
+
+                  if [ "${{ github.event_name }}" = "pull_request" ] && [ "${{ github.event.action }}" != "closed" ]; then
+                    echo "- Preview docs: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/"
+                    echo "- Preview coverage: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/coverage/"
+                    echo "- Preview metrics: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/metrics/"
+                    echo "- Preview verification: \`${{ needs.verify_preview_reports.result }}\`"
+                  fi
+
+                  if [ "${{ github.event_name }}" = "pull_request" ] && [ "${{ github.event.action }}" = "closed" ]; then
+                    echo "- Deleted preview path: \`previews/pr-${{ github.event.pull_request.number }}\`"
+                    echo "- Cleanup result: \`${{ needs.cleanup_preview.result }}\`"
+                  fi
+
+                  if [ "${{ github.event_name }}" = "schedule" ] || { [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.cleanup-previews }}" = "true" ]; }; then
+                    echo "- Cleanup summary: deleted=${{ needs.cleanup_orphaned_previews.outputs.deleted || '0' }}, skipped=${{ needs.cleanup_orphaned_previews.outputs.skipped || '0' }}, unresolved=${{ needs.cleanup_orphaned_previews.outputs.unresolved || '0' }}"
+                  fi
+
+                  echo 'EOF'
+                } >> "$GITHUB_OUTPUT"
+
+            - uses: ./.github/actions/summary/write
+              with:
+                markdown: ${{ steps.build_summary.outputs.markdown }}
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -118,3 +118,27 @@ jobs:
               env:
                 COMPOSER_ROOT_VERSION: ${{ env.TESTS_ROOT_VERSION }}
               run: composer dev-tools dependencies -- --max-outdated=${{ inputs.max-outdated || -1 }}
+
+    summarize:
+        if: ${{ always() }}
+        name: Summarize Test Workflow
+        needs:
+            - resolve_php
+            - tests
+            - dependency-health
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+
+            - uses: ./.github/actions/summary/write
+              with:
+                markdown: |
+                  ## Tests Workflow Summary
+
+                  - Workflow PHP version: `${{ needs.resolve_php.outputs.php-version }}`
+                  - PHP version source: `${{ needs.resolve_php.outputs.php-version-source }}`
+                  - Test matrix: `${{ needs.resolve_php.outputs.test-matrix }}`
+                  - Minimum coverage threshold: `${{ inputs.min-coverage || 80 }}`
+                  - Dependency health `max-outdated`: `${{ inputs.max-outdated || -1 }}`
+                  - Tests job result: `${{ needs.tests.result }}`
+                  - Dependency health result: `${{ needs.dependency-health.result }}`
diff --git a/.github/workflows/wiki-maintenance.yml b/.github/workflows/wiki-maintenance.yml
@@ -59,6 +59,17 @@ jobs:
         with:
           preview-branch: ${{ env.WIKI_PREVIEW_BRANCH }}
 
+      - uses: ./.github/actions/summary/write
+        with:
+          markdown: |
+            ## Wiki Publish Summary
+
+            - Publish branch: `${{ env.WIKI_PUBLISH_BRANCH }}`
+            - Preview branch: `${{ env.WIKI_PREVIEW_BRANCH }}`
+            - Expected preview SHA: `${{ steps.prepare_publish.outputs.expected-preview-sha }}`
+            - Publish validation: completed
+            - Preview cleanup: `${{ env.WIKI_PREVIEW_BRANCH }}` deleted
+
   cleanup_closed_preview:
     name: Delete Closed PR Wiki Preview
     if: github.event_name == 'pull_request_target' && github.event.pull_request.merged == false
@@ -86,6 +97,14 @@ jobs:
         with:
           preview-branch: ${{ env.WIKI_PREVIEW_BRANCH }}
 
+      - uses: ./.github/actions/summary/write
+        with:
+          markdown: |
+            ## Wiki Preview Cleanup Summary
+
+            - Deleted preview branch: `${{ env.WIKI_PREVIEW_BRANCH }}`
+            - Trigger: closed pull request without merge
+
   cleanup_orphaned_previews:
     name: Delete Orphaned Wiki Previews
     if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
@@ -107,4 +126,14 @@ jobs:
         run: git config --global --add safe.directory "$GITHUB_WORKSPACE/.github/wiki"
 
       - name: Delete wiki branches for closed pull requests
+        id: cleanup
         uses: ./.github/actions/wiki/cleanup-orphaned-previews
+
+      - uses: ./.github/actions/summary/write
+        with:
+          markdown: |
+            ## Wiki Orphan Cleanup Summary
+
+            - Deleted preview branches: `${{ steps.cleanup.outputs.deleted || '0' }}`
+            - Retained preview branches: `${{ steps.cleanup.outputs.skipped || '0' }}`
+            - Unresolved preview branches: `${{ steps.cleanup.outputs.unresolved || '0' }}`
diff --git a/.github/workflows/wiki-preview.yml b/.github/workflows/wiki-preview.yml
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
diff --git a/docs/advanced/consumer-automation.rst b/docs/advanced/consumer-automation.rst
diff --git a/docs/usage/github-actions.rst b/docs/usage/github-actions.rst
