Poe Command Processor

A GitHub Action to execute Poe the Poet commands in your repository, designed for use with slash commands in PR comments. This action can automatically commit changes back to the pull request branch or create a new PR if needed.

Features

• ✅ Runs any Poe command in your repository.
• ✅ Supports triggering via slash commands in PR and issue comments.
• ✅ Can auto-commit changes to the PR branch, or open a new PR if no PR exists.
• ✅ Posts status updates and results as comments on the originating comment.
• ✅ Infers commands from comment bodies for seamless gitops/chatops workflows.

Inputs

Name	Description	Required	Default
command	Poe command to run. If not provided, inferred from the body of the specified comment-id.	false
pr	Pull Request number.	false
comment-id	Comment ID (for reply chaining and command inference).	false
github-token	GitHub Token. Required for CI to run after commits are pushed.	false
no-commit	Disable auto-commit step.	false	false

Usage

Basic Example

- name: Run Poe Commanduses: aaronsteers/poe-command-processor@v1with:
command: "lint"github-token: ${{ secrets.GITHUB_TOKEN }}pr: ${{ github.event.pull_request.number }}

Slash Command Example

This action is designed to work with slash commands in PR comments. If you omit the command input and provide a comment-id, the action will extract the command from the comment body.

- name: Run Poe Command from Commentuses: aaronsteers/poe-command-processor@v1with:
comment-id: ${{ github.event.comment.id }}pr: ${{ github.event.issue.number }}github-token: ${{ secrets.GITHUB_TOKEN }}

If the comment body is /poe lint, the action will run poe lint.

Auto-Commit and PR Creation

• If changes are made and no-commit is not set to true, the action will auto-commit changes to the PR branch.
• If no PR is provided, the action will create a new draft PR with the results.
• Status and result comments are posted back to the PR or issue thread.

Requirements

• Your repository must use Poe the Poet and have a valid pyproject.toml, poe_tasks.toml, or similar config file containing the project's Poe tasks.
• The action sets up Python 3.11 and installs dependencies using uv.
• Your project should have a poe task named install which will run before any other requested command.
• The github-token input is required for committing changes and posting comments.
• Optional: If a .tool-versions file exists in the root of your repository, this action will automatically use it to determine the versions of poetry, python, and uv, provided matching entries are found. (See below.)

Tool Versions

This action will attempt to use a .tool-versions file in your repo, if one esists. This behavior is powered by the marocchino/tool-versions-action. No additional configuration is required to enable this feature.

If a .tool-versions file does not exist, or doesn't have versions specified, we will try with the following defaults:

• uv - Default to latest version.
• 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:

# 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_SUMMARYfi# Your actual task logic hereecho '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)

Show/Hide Sample Poe Workflow Files

# .github/workflows/poe-command.yml:name: On-Demand Poe Taskon:
workflow_dispatch:
inputs:
pr:
description: "PR Number. If omitted, a new PR will be created."type: stringrequired: falsecomment-id:
description: "Comment ID (Optional)"type: stringrequired: falsepermissions:
contents: writepull-requests: writeissues: writejobs:
run-poe-command:
env:
SOME_ENV_VAR: ${{ secrets.some_value }}runs-on: ubuntu-lateststeps:
- name: Run Poe Slash Command Processoruses: aaronsteers/poe-command-processor@v1with:
pr: ${{ github.event.inputs.pr }}comment-id: ${{ github.event.inputs.comment-id }}github-token: ${{ secrets.MY_GH_PAT_TOKEN }}

Sample Auto-Format Slash Command

Show/Hide Auto-Format Workflow File

# .github/workflows/format-command.yml:name: On-Demand Format Taskon:
workflow_dispatch:
inputs:
pr:
description: "PR Number. If omitted, a new PR will be created."type: stringrequired: falsecomment-id:
description: "Comment ID (Optional)"type: stringrequired: falsepermissions:
contents: writepull-requests: writeissues: writejobs:
run-poe-command:
env:
SOME_ENV_VAR: ${{ secrets.some_value }}runs-on: ubuntu-lateststeps:
- name: Run Poe Slash Command Processoruses: aaronsteers/poe-command-processor@v1with:
command: formatpr: ${{ github.event.inputs.pr }}comment-id: ${{ github.event.inputs.comment-id }}github-token: ${{ secrets.MY_GH_PAT_TOKEN }}

Sample On-Demand Test Slash Command

Show/Hide Sample Test Workflow File

# .github/workflows/test-command.yml:name: On-Demand Test Taskon:
workflow_dispatch:
inputs:
pr:
description: "PR Number. If omitted, a new PR will be created."type: stringrequired: falsecomment-id:
description: "Comment ID (Optional)"type: stringrequired: falsepermissions:
pull-requests: writeissues: writejobs:
run-poe-command:
env:
SOME_ENV_VAR: ${{ secrets.some_value }}runs-on: ubuntu-lateststeps:
- name: Run Poe Slash Command Processoruses: aaronsteers/poe-command-processor@v1with:
command: testno-commit: "true"# No changes expected from 'test' taskpr: ${{ github.event.inputs.pr }}comment-id: ${{ github.event.inputs.comment-id }}github-token: ${{ secrets.MY_GH_PAT_TOKEN }}

Sample Slash Command Dispatch Workflow

Show/Hide Sample Slash Command Dispatch File

# .github/workflows/slash-command-dispatch.yml:name: Slash Command Dispatchon:
issue_comment:
types: [created]jobs:
slashCommandDispatch:
# Only allow slash commands on pull request (not on issues)runs-on: ubuntu-lateststeps:
- name: Slash Command Dispatchid: dispatchuses: peter-evans/slash-command-dispatch@v4with:
repository: ${{ github.repository }}token: ${{ github.token }}dispatch-type: workflowissue-type: bothcommands: | poe format teststatic-args: | comment-id=${{ github.event.comment.id }} pr=${{ github.event.issue.pull_request != null && github.event.issue.number || '' }}# Only run for users with 'write' permission on the main repositorypermission: write
- name: Edit comment with error messageif: steps.dispatch.outputs.error-messageuses: peter-evans/create-or-update-comment@v4with:
comment-id: ${{ github.event.comment.id }}body: | > Error: ${{ steps.dispatch.outputs.error-message }}

Details

License

This project is licensed under the terms of the MIT License.