pi-action-runner

GitHub Action that runs AI-powered automation using pi and optionally dora for code intelligence.

Mention @pi anywhere on GitHub to trigger a response:

Where	Trigger	What happens
PR comment	`@pi review`	Structured code review posted on the PR
PR file comment	`@pi <question>`	Reads the file in context, replies in the thread
Issue	`@pi <question>`	Explores the codebase, replies in the issue
Discussion	`@pi <question>`	Explores the codebase, replies in the discussion

Only repository owners, members, and collaborators can trigger the action.

Setup

1. Add a secret

Option A: API key (recommended) -- static, never expires.

Add your provider API key as a repository secret (Settings > Secrets and variables > Actions). For example, ANTHROPIC_KEY or OPENAI_KEY.

Option B: pi auth.json -- uses your local pi OAuth session. May need periodic rotation.

base64 -i ~/.pi/agent/auth.json | pbcopy

Add as PI_AUTH secret.

2. Add the workflow

# .github/workflows/pi.yml
name: Pi
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, edited]
  discussion:
    types: [created, edited]
  discussion_comment:
    types: [created]

jobs:
  pi:
    if: |
      contains(github.event.comment.body, '@pi') ||
      contains(github.event.issue.body, '@pi') ||
      contains(github.event.discussion.body, '@pi')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
      discussions: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: >-
            ${{
              github.event.pull_request.head.sha ||
              (github.event.issue.pull_request && format('refs/pull/{0}/merge', github.event.issue.number)) ||
              github.sha
            }}

      - uses: butttons/pi-action-runner@main
        with:
          pi_auth: ${{ secrets.PI_AUTH }}
          # api_key: ${{ secrets.ANTHROPIC_KEY }}
          # pi_model: 'anthropic/claude-sonnet-4'

Usage

PR review

Comment on any PR:

@pi review

With additional context:

@pi review focus on error handling and edge cases

Inline file comment

On the Files Changed tab of a PR, leave a comment on any line:

@pi is this safe to call concurrently?

@pi what happens if this returns null?

The agent reads the full file for context before responding.

Issue

Mention @pi anywhere in an issue body when opening it, or in a follow-up comment:

We need to migrate the storage layer to D1.

@pi can you map out what currently exists and what would need to change?

The agent explores the codebase and posts a grounded reply.

Discussion

Mention @pi in a discussion body or reply:

Thinking about moving all rendering to the edge.

@pi what parts of the codebase would be hardest to migrate and why?

Inputs

Input	Default	Description
`api_key`	--	API key for the model provider. Preferred over `pi_auth`.
`pi_auth`	--	Base64-encoded pi `auth.json`. Fallback when `api_key` is not set.
`pi_model`	`opencode-go/kimi-k2.5`	Model in `provider/model-id` format.
`use_dora`	`true`	Enable dora code intelligence.
`dora_version`	`latest`	Dora CLI version tag.
`scip_install`	`bun install -g @sourcegraph/scip-typescript`	SCIP indexer install command. Set to empty string to skip.
`dora_pre_index`	--	Commands to run after `dora init` but before indexing (e.g. install project deps).
`dora_index_command`	`dora index`	Override the dora index command.
`project_lockfile`	--	Path to your project lockfile (e.g. `pnpm-lock.yaml`). When set, `node_modules` is cached across runs.
`system_prompt`	--	Path to a custom system prompt for PR reviews (relative to repo root).
`review_template`	--	Path to a custom review output template (relative to repo root).
`extra_prompt`	--	Additional instructions appended to every review prompt.
`obsidian_vault_repo`	--	GitHub repo containing an Obsidian vault (e.g., `owner/repo`).
`obsidian_vault_name`	--	Vault name for `obi --vault` flag (defaults to repo name).
`obsidian_token`	--	GitHub token for private vault repos (defaults to `GITHUB_TOKEN`).
`obsidian_prompt`	--	Additional instructions for using the obsidian vault via `obi` CLI.
`exa_api_key`	--	Exa AI API key for web search via the `exa_search` tool.

Either api_key or pi_auth must be provided. When both are set, api_key takes precedence.

Examples

Monorepo with pnpm

- uses: butttons/pi-action-runner@main
  with:
    pi_auth: ${{ secrets.PI_AUTH }}
    project_lockfile: 'pnpm-lock.yaml'
    dora_pre_index: 'pnpm install --frozen-lockfile'

Large codebase (increase Node heap for dora indexing)

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.ANTHROPIC_KEY }}
    dora_index_command: 'NODE_OPTIONS="--max-old-space-size=6144" dora index'

Rust project

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.API_KEY }}
    scip_install: 'cargo install rust-analyzer'

Python project

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.API_KEY }}
    scip_install: 'pip install scip-python'
    dora_pre_index: 'pip install -e .'

Without dora

Uses git diff, grep, find, and direct file reading only. Faster setup, no indexing.

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.API_KEY }}
    use_dora: 'false'

With Obsidian vault

Connect an Obsidian vault from another repo to give the agent access to documentation and architecture notes.

Setup:

Create a GitHub Personal Access Token with contents:read scope for your vault repo
Add it as a repository secret (e.g., OBSIDIAN_TOKEN) in the repo where the action runs

Usage:

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.API_KEY }}
    obsidian_vault_repo: 'myorg/documentation'
    obsidian_vault_name: 'Docs'  # optional, defaults to repo name
    obsidian_token: ${{ secrets.OBSIDIAN_TOKEN }}  # required for private vaults
    obsidian_prompt: |
      Before making architectural decisions, check the vault for documented patterns.
      Search for relevant docs using `obi search` and read the full notes.

The agent can use the obi CLI to query the vault:

obi map --vault "VaultName" - see vault structure
obi read "path/to/note.md" --vault "VaultName" - read specific notes
obi search "term" --vault "VaultName" - search content
obi query --type worker --vault "VaultName" - filter by frontmatter type

With extensions (exa-search, etc.)

Extensions add custom tools to the agent. The action supports any pi-compatible extension.

Available extensions from pi-kit:

Extension	Tool	Description	Required Secret
`exa-search`	`exa_search`	Web search via Exa AI	`EXA_API_KEY`

Setup:

Add the extension's API key as a GitHub secret (e.g., EXA_API_KEY for exa-search)
Configure your workflow to clone the extensions and create a pi settings file:

- name: Setup pi extensions
  shell: bash
  run: |
    mkdir -p "$HOME/.pi/agent/git/github.com/butttons"
    git clone --depth 1 "https://github.com/butttons/pi-kit.git" "$HOME/.pi/agent/git/github.com/butttons/pi-kit"
    cat > "$HOME/.pi/agent/settings.json" << 'EOF'
    {
      "packages": [
        {
          "source": "git:github.com/butttons/pi-kit"
        }
      ]
    }
    EOF

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.ANTHROPIC_KEY }}
    exa_api_key: ${{ secrets.EXA_API_KEY }}

Usage in prompts:

Once configured, the agent can use extension tools:

@pi search for the latest React best practices and compare them to our codebase

@pi use exa_search to find documentation for the error handling pattern we're using

Caching: Extensions are cached by commit SHA for fast warm runs.

Different model

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.ANTHROPIC_KEY }}
    pi_model: 'anthropic/claude-sonnet-4'

Customizing prompts

PR review

The system prompt and output template for PR reviews are fully replaceable. Defaults are in prompts/:

prompts/system-dora.md -- used when dora is enabled
prompts/system-git.md -- used when dora is disabled
prompts/review-template.md -- output structure

Point the inputs to your own files:

- uses: butttons/pi-action-runner@main
  with:
    api_key: ${{ secrets.API_KEY }}
    system_prompt: '.github/review-prompt.md'
    review_template: '.github/review-template.md'

Use {base_branch} in your system prompt -- it gets replaced with the PR's target branch (e.g. main).

Inline comments, issues, discussions

Drop a markdown file in .pi/prompts/ in your repo to override the default system prompt for each handler:

File	Overrides
`.pi/prompts/inline-comment.md`	Inline PR file comment handler
`.pi/prompts/issue.md`	Issue handler
`.pi/prompts/discussion.md`	Discussion handler

Caching

The action caches the following automatically:

What	Cache key
Bun binary	Managed by `setup-bun`
Action `node_modules`	Hash of `bun.lock`
dora + scip globals (`~/.bun`)	dora version + scip install command
Dora index (`.dora/`)	Commit SHA -- busted on every new commit
Project `node_modules`	Hash of `project_lockfile` -- only when `project_lockfile` is set
Obsidian vault (`/home/runner/obi-vaults/{vault-name}/`)	Vault repo + commit SHA
pi-kit extensions (`~/.pi/agent/git/github.com/butttons/pi-kit`)	pi-kit commit SHA

On a warm run (same commit, same deps), only the dora agent itself runs -- all installs and indexing are skipped.

How it works

Validates the commenter is a repo owner, member, or collaborator.
Routes based on the GitHub event:
- issue_comment on a PR → @pi review triggers a full review
- pull_request_review_comment → reads the file, replies to the thread
- issues / issue_comment on a plain issue → explores codebase, replies in the issue
- discussion / discussion_comment → explores codebase, replies in the discussion
If dora is enabled: installs dora + SCIP indexer (cached), runs dora init + dora index (cached per commit).
Loads extensions from ~/.pi/agent/settings.json if configured (cached by commit SHA).
Runs the pi agent with bash, read, and any extension tools. The agent uses dora commands, extension tools (like exa_search), git diff, grep, find, and direct file reading to gather context.
Posts the response via the appropriate GitHub API (REST for PRs/issues, GraphQL for discussions).

Requirements

GitHub Actions runner: ubuntu-latest
One of: a provider API key or a base64-encoded pi auth.json

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
prompts		prompts
skills/obi		skills/obi
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
action.yml		action.yml
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

pi-action-runner

Setup

1. Add a secret

2. Add the workflow

Usage

PR review

Inline file comment

Issue

Discussion

Inputs

Examples

Monorepo with pnpm

Large codebase (increase Node heap for dora indexing)

Rust project

Python project

Without dora

With Obsidian vault

With extensions (exa-search, etc.)

Different model

Customizing prompts

PR review

Inline comments, issues, discussions

Caching

How it works

Requirements

License

About

Uh oh!

Releases 3

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

pi-action-runner

Setup

1. Add a secret

2. Add the workflow

Usage

PR review

Inline file comment

Issue

Discussion

Inputs

Examples

Monorepo with pnpm

Large codebase (increase Node heap for dora indexing)

Rust project

Python project

Without dora

With Obsidian vault

With extensions (exa-search, etc.)

Different model

Customizing prompts

PR review

Inline comments, issues, discussions

Caching

How it works

Requirements

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Contributors

Uh oh!

Languages