Pi Coding Agent GitHub Action

This is a GitHub action that integrates Pi coding agent with GitHub workflows (issues, pull requests, etc.).

Inspired by OpenCode's GitHub action.

Features

• Issue assistance: Prefix any new issue description and/or any issue comment with /pi to have the agent analyze the issue and e.g. create a new PR with the fix
• PR assistance: Prefix any PR comment/review comment/review message with /pi to have the agent review and improve the pull request
• Automated code reviews: Have Pi review every new pull request automatically
• Add Pi to your own pipelines: (Optionally) generate prompt from upstream actions/workflows and have Pi do the work in background for you anywhere you like in your workflows

Securing your workflows

Warning

Depending on the permissions assigned to your workflow you should consider restricting who's allowed to trigger it e.g. filtering for GitHub user name or role (if github.actor == '<my-user>').

Important

The default v2 branch is in active development so if you don't want the bleeding edge you should pin to the latest release, e.g.

   uses: shaftoe/pi-coding-agent-action@v2.8.1

Usage

Interactive Workflows

• Create a GitHub workflow which triggers when comments are added (e.g., issue_comment)
• Filter by if to only run on the trigger phrase (e.g., contains(github.event.comment.body, '/pi'))
• Add actions/checkout and actions/setup-node as prerequisite steps
• Finally, add shaftoe/pi-coding-agent-action

Example:

name: Pi Agent

on:
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  pi-agent:
    if: contains(github.event.comment.body, '/pi')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Run Pi agent
        uses: shaftoe/pi-coding-agent-action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          provider: my-provider
          model: some-model
          token: ${{ secrets.MODEL_API_KEY }}
          thinking_level: medium

Non-Interactive Workflows

You can use the prompt input to run the agent without requiring a comment trigger. This is useful for automated workflows like PR reviews, scheduled tasks, or prompts generated by a previous step:

      - name: Run Pi agent with fixed prompt
        uses: shaftoe/pi-coding-agent-action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          provider: anthropic
          model: claude-opus-4-7
          token: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: 'Review this pull request for security issues' # or e.g. ${{ steps.generate-prompt.outputs.prompt }}

When using the prompt input, the action still enriches the prompt with issue/PR context (title and description) if available in the workflow context.

Custom Extensions

You can load custom Pi extensions to add additional tools, custom tools, or modify agent behavior:

      - name: Run Pi agent with extensions
        uses: shaftoe/pi-coding-agent-action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          provider: anthropic
          model: claude-opus-4-7
          token: ${{ secrets.ANTHROPIC_API_KEY }}
          extensions: |
            npm:pi-subagents
            git:github.com/user/pi-custom-tools
            ./my-local-extension.ts

Supported extension sources:

• npm packages: npm:package-name or npm:package@version
• git repositories: git:github.com/user/repo (supports branches with #branch)
• local files: Relative paths to .ts extension files

Disabling Built-in Extensions

By default the action loads three built-in GitHub related tools (create_pull_request, update_pull_request, get_issue_or_pr_thread) to help Pi better interact with GitHub action environment without relying on external tools like gh nor need special skills setup for that. If you want Pi to use only your own custom extensions (or none at all), set load_builtin_extensions to false:

      - name: Run Pi agent
        uses: shaftoe/pi-coding-agent-action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          provider: anthropic
          model: claude-opus-4-7
          token: ${{ secrets.ANTHROPIC_API_KEY }}
          load_builtin_extensions: false
          extensions: |
            npm:my-custom-github-tools

Quick Start

Create a workflow file, e.g., .github/workflows/pi-agent.yml. See the interactive and non-interactive workflows in this repository to get started.

Inputs

Input	Description	Required	Default
github_token	GitHub token for API access	Yes	-
provider	LLM provider (anthropic, openai, google, etc.)	Yes	-
model	Model to use (e.g., claude-sonnet-4-5, claude-opus-4-7, gpt-4o, gemini-2.5-pro)	Yes	-
token	Provider API token	Yes	-
thinking_level	Model thinking level (off	low	medium
trigger	Trigger phrase used to invoke the action	No	/pi
prompt	Optional prompt to send to the agent (skips comment extraction)	No	-
extensions	Custom Pi extensions to load (one per line). Supports npm packages (npm:package-name), git repos (git:github.com/user/repo), or local file paths	No	-
load_builtin_extensions	Whether to load built-in GitHub extensions (create_pull_request, update_pull_request, get_issue_or_pr_thread)	No	true

Refer to Pi documentation for the current list of supported providers / models / etc.

How It Works

1. User comments /pi [instructions] in an issue or PR
2. Action fetches issue/PR context via GitHub API
3. Creates a new branch: pi/issue{number}-{timestamp}
4. Runs Pi agent with the issue/PR context
5. If changes are made:
   • Stages all modified files via Git Data API
   • Commits with AI-generated summary
   • Pushes to remote via GitHub API
   • Creates a new PR
6. Posts result as a comment with metadata footer

Custom Tools

The action extends Pi with three custom tools:

Tool	Description
create_pull_request	Creates a new pull request by detecting file changes, creating a branch, committing changes via GitHub API, and opening the PR. Supports dry_run mode for testing without actual PR creation.
update_pull_request	Updates an existing pull request by pushing new commits to the PR branch and optionally updating the title and/or description. Supports dry_run mode for testing without actual modifications.
get_issue_or_pr_thread	Retrieves the full thread of an issue or pull request including title, body, state, labels, branch info (for PRs), and all comments. Useful for understanding the full context before making changes.

Data Flow via comment trigger

1. Trigger Detection: Action reads GitHub event payload to determine if triggered by comment or direct prompt
2. Context Extraction: github/context.ts extracts issue/PR metadata and enriches prompt
3. Reaction Management: github/reactions.ts adds "eyes" reaction for visual feedback
4. Session Initialization: pi/agent.ts creates Pi agent session with model, auth, and resource loader
5. Prompt Execution: User prompt sent to agent with streaming output
6. Tool Invocations: Custom tools invoked via pi/tools/ extensions:
   • get_issue_or_pr_thread for context
   • create_pull_request / update_pull_request for making changes
7. Git Operations: github/git/ module handles all Git operations via GitHub API:
8. Finalization: Reaction removed, final comment posted with metadata footer by github/comments.ts

Development

Prerequisites

• Bun package manager
• Node.js 24+

Validation

Before committing, run the following checks:

bun run validate

This runs:

• Code formatting (Prettier)
• Linting (ESLint)
• Type checking (TypeScript)
• Building

Testing

The project uses bun test for testing:

# Run all tests
bun test

# Run tests with coverage
bun run test:coverage

# Watch mode for development
bun run test:watch

# Run end to end tests (requires env vars properly set, see below)
bun run test:e2e

Test Architecture

The test suite emphasizes behavior verification over implementation details:

• Orchestrator tests (tests/orchestrator.spec.ts) - Tests business logic flow:

  • Configuration gathering from inputs
  • Prompt retrieval and validation
  • Reaction lifecycle management
  • Pi agent execution
  • Error handling and finalization
  • Early exit scenarios

• GitHub module tests:

  • tests/github.spec.ts - GitHub module integration tests
  • tests/github/comments.spec.ts - Comment creation and formatting
  • tests/github/git.spec.ts - Git operations via GitHub API
  • tests/github/pull-request-logic.spec.ts - PR creation logic
  • tests/github/pull-request-update-logic.spec.ts - PR update logic

• Pi module tests:

  • tests/pi/agent-logic.spec.ts - Pi agent behavior tests
  • tests/pi/logging.spec.ts - Centralized logging tests
  • tests/pi/tools.spec.ts - Tool interface tests
  • tests/pi/tools/*.spec.ts - Tool execution tests for each tool

• E2E tests (tests/e2e/pi-agent.spec.ts) - Real Pi SDK integration with actual API calls

Key principle: Tests verify the orchestration flow and business logic, not the behavior of mocks. The adapter pattern enables testing the actual behavior of the action without requiring external services.

E2E Tests

E2E (end-to-end) tests validate that our Pi SDK integration works correctly with real API calls:

# Set up E2E tests (example using OpenRouter with free model)
export E2E_PROVIDER=openrouter
export E2E_MODEL=google/gemma-3-4b-it:free
export E2E_TOKEN=sk-or-xxx
export RUN_E2E_TESTS=1
bun test tests/e2e/pi-agent.spec.ts

Required environment variables:

• RUN_E2E_TESTS=1 - Enables E2E tests (they are skipped by default)
• E2E_PROVIDER - LLM provider (e.g., openrouter, zai, anthropic)
• E2E_MODEL - Model to use (e.g., google/gemma-3-4b-it:free, glm-4.5-air:free)
• E2E_TOKEN - Your API key for the provider

What E2E tests cover:

• Real Pi SDK initialization with actual model/provider/token
• Complete agent session lifecycle (ready → run → result)
• Session stats extraction (tokens, cost, version)
• Error handling for invalid models, empty prompts, etc.
• Multiple sequential calls to the same agent

Note: E2E tests make real API calls to the LLM provider and may incur costs. You must explicitly set the provider, model, and API key - there are no defaults. Tests are opt-in only and skipped by default.

Project Guidelines

• Follow the existing code style and conventions
• Add tests for new functionality
• Update documentation as needed
• Use bun as the package manager (preferred over npm)
• Run bun run validate before committing

Releasing

Automated release flow handled by semantic-release in release.yml

Refereneces

• Events that trigger workflows: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows
• Webhook schema source: https://github.com/octokit/webhooks/tree/main/payload-schemas/api.github.com

License

See LICENSE