https://github.com/shaftoe/pi-coding-agent-action
GitHub action to integrate https://pi.dev/ coding agent with GitHub-compatible CI/CD, issues and PRs
https://github.com/shaftoe/pi-coding-agent-action
ai-assisted code-review coding-agents github-actions pi-coding-agent
Last synced: 26 days ago
JSON representation
GitHub action to integrate https://pi.dev/ coding agent with GitHub-compatible CI/CD, issues and PRs
- Host: GitHub
- URL: https://github.com/shaftoe/pi-coding-agent-action
- Owner: shaftoe
- License: mit
- Created: 2026-03-21T21:59:59.000Z (about 2 months ago)
- Default Branch: v2
- Last Pushed: 2026-04-21T12:50:32.000Z (28 days ago)
- Last Synced: 2026-04-21T14:19:33.155Z (28 days ago)
- Topics: ai-assisted, code-review, coding-agents, github-actions, pi-coding-agent
- Language: TypeScript
- Homepage:
- Size: 39.6 MB
- Stars: 17
- Watchers: 1
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Pi Coding Agent Action
[](https://app.codecov.io/gh/shaftoe/pi-coding-agent-action/)
A CI/CD action that integrates [Pi coding agent](https://pi.dev) with git hosting platform workflows. Works with **GitHub**, **Codeberg**, and self-hosted **Forgejo** instances — any platform that provides GitHub-compatible APIs and CI/CD environment variables.
Inspired by OpenCode's [GitHub action](https://opencode.ai/docs/github/).
## 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
- **Minimal batteries included**: Tries to follow Pi minimalistic phylosophy while providing a comfortable UX out of the box, e.g. pretty print of logs, auto replies to comments, and tools to interact efficiently with git and GitHub-compatible APIs.
## Goal
If all you want is running Pi inside a CI/CD environment technically you don't need any custom action, something like
```yaml
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm -g install @mariozechner/pi-coding-agent
- run: pi -p "do something useful for me"
```
might be just good enough and probably will always be the best fit for a pure "as minimalist as Pi" approach.
On the other hand that's true for almost everything which is offered by the Actions ecosystem, useful and popular Actions are mostly focused on providing a pleasant UX around the raw core functionality they provide.
This project goal is exactly that: to provide a short list of (opt-out) opinionated default features for interacting with and executing Pi agent sessions inside CI/CD environments compatible with GitHub API.
For all the rest you're free and encouraged to just configure the action environment as you would your local Pi instance, e.g. adding files to `~/.pi/agent/`, environment variables, etc., and more generally to compose workflow pipelines around this action's inputs and outputs to fullfill your specific needs.
Refer to [the official Pi documentation](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#customization) to learn how to tweak Pi to best fit your needs.
## Disclaimer
> [!NOTE]
> Codeberg/Forgejo compatibility _should_ work but hasn't been tested yet.
## 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 == ''`).
> [!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.
> ```yaml
> uses: shaftoe/pi-coding-agent-action@v2.12.0
> ```
## 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:
```yaml
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:
```yaml
- 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:
```yaml
- 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`:
```yaml
- 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
```
### Injecting Environment Variables
Pi extensions often require environment variables for authentication or configuration. Use the native `env:` step key to pass variables from your workflow's secrets or configuration into the Pi session:
```yaml
- name: Run Pi agent with custom env vars
uses: shaftoe/pi-coding-agent-action@v2
env:
MY_API_KEY: ${{ secrets.MY_API_KEY }}
ANOTHER_SERVICE_TOKEN: ${{ secrets.ANOTHER_SERVICE_TOKEN }}
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
provider: anthropic
model: claude-opus-4-7
token: ${{ secrets.ANTHROPIC_API_KEY }}
```
Since the action runs as a single Node.js process, these environment variables are available in `process.env` and accessible to all Pi extensions.
### Using Outputs in Downstream Jobs
Use `outputs..outputs.` to pass action outputs to another step or another job in the same workflow. For example, you can have Pi generate release notes in one job and then create a release in another:
```yaml
jobs:
pi-agent:
# shortened for brevity...
- name: Run Pi agent
id: pi # Required to access outputs from this step
uses: shaftoe/pi-coding-agent-action@v2
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
provider: anthropic
model: claude-sonnet-4-5
token: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: 'Generate release notes for the latest commit'
publish:
needs: pi-agent
if: ${{ needs.pi-agent.outputs.success == 'true' }}
runs-on: ubuntu-latest
steps:
- name: Log results
run: |
echo "Response: ${{ needs.pi-agent.outputs.response }}"
echo "Cost: ${{ needs.pi-agent.outputs.cost }} USD"
echo "Tokens: ${{ needs.pi-agent.outputs.input_tokens }} in / ${{ needs.pi-agent.outputs.output_tokens }} out"
echo "Duration: ${{ needs.pi-agent.outputs.duration_seconds }}s"
- name: Create GitHub release
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
echo '${{ needs.pi-agent.outputs.response }}' > release-notes.md
gh release create v1.0.0 --notes-file release-notes.md
```
### Quick Start
Create a workflow file, e.g., `.github/workflows/pi-agent.yml`. See the [interactive](./.github/workflows/pi.yml) and [non-interactive](./.github/workflows/pr.yml) workflows in this repository to get started.
## Inputs
| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `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 | - |
| `github_token` | GitHub token for API access | Yes | - |
| `load_builtin_extensions` | Whether to load built-in GitHub extensions (`create_pull_request`, `update_pull_request`, `get_issue_or_pr_thread`) | No | `true` |
| `model` | Model to use (e.g., claude-sonnet-4-5, claude-opus-4-7, gpt-4o, gemini-2.5-pro) | Yes | - |
| `prompt` | Optional prompt to send to the agent (skips comment extraction) | No | - |
| `provider` | LLM provider (anthropic, openai, google, etc.) | Yes | - |
| `thinking_level` | Model thinking level (off|low|medium|high) | No | off |
| `token` | Provider API token | Yes | - |
| `trigger` | Trigger phrase used to invoke the action | No | /pi |
Refer to [Pi documentation](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) for the current list of supported providers / models / etc.
## Outputs
The action exposes the following outputs, which can be consumed by downstream steps or jobs:
| Output | Description | Example |
|--------|-------------|----------|
| `response` | The main agent response text (or error message on failure) | `Here is the fix for the bug...` |
| `success` | Whether the agent completed successfully (`true` / `false`) | `true` |
| `input_tokens` | Number of input tokens consumed (omitted if unavailable) | `1500` |
| `output_tokens` | Number of output tokens generated (omitted if unavailable) | `800` |
| `cost` | Cost of the invocation in USD (omitted if unavailable) | `0.042` |
| `duration_seconds` | Wall-clock duration of agent execution in seconds | `12.7` |
> [!WARNING]
> Tokens and cost outputs are only set when the underlying provider returns session statistics. They will be absent for providers that don't report token usage.
## 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. |
> [!TIP]
> Set `load_builtin_extensions` input to `false` to disable custom tool auto loading.
## Development
### Prerequisites
- Bun package manager
- Node.js 24+
### Validation
Before committing, run the following checks:
```bash
bun run validate
```
This runs:
- Code formatting (Prettier)
- Linting (ESLint)
- Type checking (TypeScript)
- Building
### Testing
The project uses `bun test` for testing:
```bash
# 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 LLM to be setup)
bun run test:e2e
```
### 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](./.github/workflows/release.yml)
### Refereneces
- Events that trigger workflows:
- Webhook schema source:
## License
See [LICENSE](./LICENSE)