feat: Add GITHUB_STEP_SUMMARY output to PR comments (#17)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: aaronsteers

.github/workflows/ci-tests.yml

@@ -0,0 +1,60 @@
+name: CI Tests
+
+on:
+  pull_request:
+    types: [synchronize, opened, reopened, ready_for_review]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  test-success:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run `poe test-success` [Poe Command Processor]
+        uses: ./
+        with:
+          pr: ${{ github.event.pull_request.number }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: test-success
+
+  test-success-with-summary:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run `poe test-success-with-summary` [Poe Command Processor]
+        uses: ./
+        with:
+          pr: ${{ github.event.pull_request.number }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: test-success-with-summary
+
+  test-fail-with-summary:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run `poe test-fail-with-summary` [Poe Command Processor]
+        uses: ./
+        continue-on-error: true
+        with:
+          pr: ${{ github.event.pull_request.number }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: test-fail-with-summary

README.md

@@ -72,6 +72,37 @@ If a `.tool-versions` file does not exist, or doesn't have versions specified, w
 - `poetry` - Default to latest version.
 - `python` - Default to version 3.11.
 
+## Publishing Task Output
+
+Tasks can optionally publish markdown output that will appear in both the GitHub job summary and as an expandable section in PR comments. This is useful for displaying test results, coverage reports, or other structured output.
+
+### How It Works
+
+To publish output, your poe task should check for the `GITHUB_STEP_SUMMARY` environment variable and write markdown content to it:
+
+```shell
+# In your poe task (pyproject.toml or poe_tasks.toml)
+[tasks.my-task]
+shell = """
+if [ -n "$GITHUB_STEP_SUMMARY" ]; then
+  echo '## Task Results' >> $GITHUB_STEP_SUMMARY
+  echo '' >> $GITHUB_STEP_SUMMARY
+  echo '- ✅ Step 1: Success' >> $GITHUB_STEP_SUMMARY
+  echo '- ✅ Step 2: Success' >> $GITHUB_STEP_SUMMARY
+  echo '' >> $GITHUB_STEP_SUMMARY
+  echo '**Status**: All steps completed! 🎉' >> $GITHUB_STEP_SUMMARY
+fi
+# Your actual task logic here
+echo 'Task completed'
+"""
+```
+
+The output will appear:
+- In the GitHub Actions job summary (visible in the workflow run page)
+- In PR comments as an expandable section with ✳️ "Show/Hide Summary Output" (on success) or ✴️ (on failure)
+
+**Note:** Always check if `GITHUB_STEP_SUMMARY` is defined before writing to it, as this variable is only available in GitHub Actions environments.
+
 ## Sample Workflows
 
 ### Sample Poe Slash Command (Generic)

action.yml

@@ -179,20 +179,40 @@ runs:
 
     - name: Run `poe ${{ steps.resolve-command.outputs.command }}`
       shell: bash
+      id: run-poe-task
       run: |
+        set -euo pipefail
+
+        set +e  # Temporarily disable exit on error to capture exit code
+
         poe ${{ steps.resolve-command.outputs.command }}
 
-    - name: Print Post-Run Marker
-      if: always()
-      shell: bash
-      run: |
+        EXIT_CODE=$?
+        set -e  # Re-enable exit on error
+
         # Printing Post-Run Marker
         echo "------------------------------------"
         echo "------------------------------------"
         echo "-- Execution Completed: 'poe ${{ steps.resolve-command.outputs.command }}' --"
         echo "------------------------------------"
         echo "------------------------------------"
 
+        if [ -s "$GITHUB_STEP_SUMMARY" ]; then
+          echo "Step summary file exists and is non-empty: $GITHUB_STEP_SUMMARY"
+          # Use multiline output syntax for GitHub Actions
+          {
+            echo "has-summary=true"
+            echo "summary-text<<__POE_EOF__"
+            cat "$GITHUB_STEP_SUMMARY"
+            echo "__POE_EOF__"
+          } >> "$GITHUB_OUTPUT"
+        else
+          echo "No step summary content found."
+          echo "has-summary=false" >> $GITHUB_OUTPUT
+          echo "summary-text=" >> $GITHUB_OUTPUT
+        fi
+        exit "$EXIT_CODE"
+
     - name: Auto commit changes
       id: auto-commit
       uses: stefanzweifel/git-auto-commit-action@v5
@@ -215,7 +235,7 @@ runs:
         body: >
           🤖 Auto-commit successful: ${{ steps.auto-commit.outputs.commit_hash }}
 
-    - name: Append no-op comment
+    - name: Append success comment with output
       if: >
         steps.comment-start.outputs.comment-id
       uses: peter-evans/create-or-update-comment@v4
@@ -224,15 +244,29 @@ runs:
         reactions: "+1"
         body: |
           > ${{ inputs.success-message || format(' 🟦 Poe command `{0}` completed successfully.', steps.resolve-command.outputs.command) }}
+          ${{ steps.run-poe-task.outputs.has-summary == 'true' && format('
+
+          <details><summary>✳️ Show/Hide Summary Output</summary>
+
+          {0}
+
+          </details>', steps.run-poe-task.outputs.summary-text) || '' }}
 
     - name: Append failure comment
       if: failure() && steps.comment-start.outputs.comment-id
       uses: peter-evans/create-or-update-comment@v4
       with:
         comment-id: ${{ steps.comment-start.outputs.comment-id }}
         reactions: confused
-        body: >
-          ${{ inputs.failure-message || format('❌ Poe command `{0}` failed. Please inspect the logs.', steps.resolve-command.outputs.command) }}
+        body: |
+          > ${{ inputs.failure-message || format('❌ Poe command `{0}` failed. Please inspect the logs.', steps.resolve-command.outputs.command) }}
+          ${{ steps.run-poe-task.outputs.has-summary == 'true' && format('
+
+          <details><summary>✴️ Show/Hide Summary Output</summary>
+
+          {0}
+
+          </details>', steps.run-poe-task.outputs.summary-text) || '' }}
 
     # Create a new PR if no PR was provided
 

poe_tasks.toml

@@ -1,3 +1,36 @@
 [tasks]
-test = "echo 'Dummy tests...'"
+test-success = "echo 'Dummy tests...'"
 test-fail = "exit 1"
+
+[tasks.test-success-with-summary]
+shell = """
+if [ -n "$GITHUB_STEP_SUMMARY" ]; then
+  echo '## Test Results' >> "$GITHUB_STEP_SUMMARY"
+  echo '' >> "$GITHUB_STEP_SUMMARY"
+  echo 'This is a test of the GITHUB_STEP_SUMMARY feature.' >> "$GITHUB_STEP_SUMMARY"
+  echo '' >> "$GITHUB_STEP_SUMMARY"
+  echo '- ✅ Item 1: Success' >> "$GITHUB_STEP_SUMMARY"
+  echo '- ✅ Item 2: Success' >> "$GITHUB_STEP_SUMMARY"
+  echo '- ✅ Item 3: Success' >> "$GITHUB_STEP_SUMMARY"
+  echo '' >> "$GITHUB_STEP_SUMMARY"
+  echo '**Status**: All tests passed! 🎉' >> "$GITHUB_STEP_SUMMARY"
+fi
+echo 'Test with summary completed'
+"""
+
+[tasks.test-fail-with-summary]
+shell = """
+if [ -n "$GITHUB_STEP_SUMMARY" ]; then
+  echo '## Test Results' >> "$GITHUB_STEP_SUMMARY"
+  echo '' >> "$GITHUB_STEP_SUMMARY"
+  echo 'This is a test of the GITHUB_STEP_SUMMARY feature.' >> "$GITHUB_STEP_SUMMARY"
+  echo '' >> "$GITHUB_STEP_SUMMARY"
+  echo '- ✅ Item 1: Success' >> "$GITHUB_STEP_SUMMARY"
+  echo '- ✅ Item 2: Success' >> "$GITHUB_STEP_SUMMARY"
+  echo '- 😵 Item 3: Failure!!' >> "$GITHUB_STEP_SUMMARY"
+  echo '' >> "$GITHUB_STEP_SUMMARY"
+  echo '**ERROR**: Something bad happened ☠️' >> "$GITHUB_STEP_SUMMARY"
+fi
+echo 'Test fail with summary completed'
+exit 1
+"""