# Pi GitHub Identity

Run selected GitHub CLI actions from Pi through a separate bot identity, without taking over your normal `gh` or Git workflow.

A "bot identity" means a separate GitHub user account that you provision yourself, for example `my-name-bot`. This extension does not create a GitHub account, GitHub App, or installation token for you.

## Philosophy

This package is for selected GitHub actions where bot attribution matters: filing issues, responding to PR review comments, replying to GitHub content written by the user, and actions explicitly requested as the bot. Other GitHub work stays on the user's normal identity. The bot is an ordinary GitHub account, so GitHub permissions work exactly like any other user: add it as a collaborator or org member where it should act.

By default it does **not** force all Pi shell commands to use the bot. Your normal `bash`/`gh`/`git` usage can stay as you. The extension adds an explicit `gh_bot` tool that the agent should use when a GitHub action should appear from the bot account.

## What it does

- Keeps bot GitHub CLI auth in a separate config dir:
  - default: `~/.config/gh-bot`
  - override: `PI_GH_BOT_CONFIG_DIR=/path/to/config`
- Adds `gh_bot` tool for running `gh` with bot `GH_CONFIG_DIR`.
- Adds automatic prompt guidance so Pi uses `gh_bot` only for issue filing, replies to review/user-written content, and explicit bot requests.
- Adds a bash guard that redirects mechanically identifiable bot-default actions (`gh issue create` and review-thread reply APIs) to `gh_bot`.
- Removes token env vars from `gh_bot` calls so `GH_CONFIG_DIR` auth wins:
  - `GH_TOKEN`
  - `GITHUB_TOKEN`
  - `GH_ENTERPRISE_TOKEN`
  - `GITHUB_ENTERPRISE_TOKEN`
- Supports `PI_GH_BOT_EXPECTED_LOGIN=bot-login` fail-closed identity enforcement.
- Shows Pi footer status for the bot account:
  - `gh: <login>` when bot auth is ready
  - `gh: auth-missing` when bot auth is missing
  - `gh: wrong-account` when authenticated account does not match `PI_GH_BOT_EXPECTED_LOGIN`

## Tool

### `gh_bot`

Runs GitHub CLI as the bot identity. Args are `gh` args without the leading `gh`.

Use cases:

- File issues as bot.
- Reply to PR review comments as bot.
- Reply to GitHub content written by the user.
- Run another GitHub action when the user explicitly requests bot attribution.

Examples of underlying commands the tool can run:

```bash
gh issue comment 123 --body "..."
gh pr comment 456 --body "..."
gh api repos/OWNER/REPO/pulls/PR/comments -f body="..." ...
```

Normal shell `gh` remains your existing identity unless you choose otherwise.

## Automatic routing

On install, the extension changes Pi behavior in three ways:

1. **Tool guidance**: `gh_bot` advertises its narrow policy: file issues, respond to review comments, reply to user-written GitHub content, or honor an explicit bot request.
2. **Per-turn prompt note**: every user turn gets that routing rule; all other GitHub actions use normal tools and identity.
3. **Bash guard**: if the model tries a mechanically identifiable bot-default action through `bash`, the extension blocks the call and tells the model to retry with `gh_bot`.

Guarded bash patterns include:

```bash
gh issue create ...
gh api .../pulls/.../comments/.../replies ...
gh api graphql ...addPullRequestReviewThreadReply...
```

Whether a general issue/PR comment replies to user-written content depends on conversation context, so prompt guidance—not a broad shell block—routes those cases. Unsolicited comments and reviews stay on the user's identity.

If you explicitly want to comment/review as yourself, either ask Pi to use normal `gh` as you or disable the guard:

```bash
PI_GH_BOT_AUTO_GUARD=0 pi
```

## Provision the bot account

Before using the extension:

1. Create/register a separate GitHub account for the bot.
2. Add that account to repos/orgs where it should act:
   - public repos may allow some actions without explicit access, depending on repo settings
   - private repos require collaborator/org membership
   - PR review comments require permission to the target repo
3. Run `/gh-bot-auth` and authorize **that bot account** in the browser.
4. Optional but recommended: set `PI_GH_BOT_EXPECTED_LOGIN=<bot-login>` so accidental personal-account auth fails closed.

If the bot lacks repo access, `gh_bot` fails with GitHub's normal permission error. That is expected and safer than silently using your personal account.

## Commands

### `/gh-bot-status`

Shows bot GitHub login and `GH_CONFIG_DIR`. If bot auth is missing, offers to start browser auth.

### `/gh-bot-auth`

Starts GitHub CLI browser/device auth for the bot config dir:

```bash
gh auth login --hostname github.com --web --clipboard --git-protocol https --skip-ssh-key
```

Pi shows the one-time code and auth URL above the editor while `gh` waits for completion.

> Important: `GH_CONFIG_DIR` controls where the CLI token is stored. The browser still decides which GitHub account authorizes that token. Use the separate bot GitHub account you provisioned. If GitHub opens as your personal account, switch accounts or use an incognito/private window logged in as the bot before entering the code.

## Install

From npm, after publish:

```bash
pi install npm:pi-github-identity
```

From GitHub:

```bash
pi install git:github.com/adstastic/pi-github-identity
```

From local checkout:

```bash
pi install /Users/adi/code/pi-github-identity
```

Development symlink:

```bash
mkdir -p ~/.pi/agent/extensions
ln -s /Users/adi/code/pi-github-identity/src/index.ts ~/.pi/agent/extensions/github-identity.ts
```

Restart Pi, or run:

```text
/reload
```

## Usage

Authenticate bot:

```text
/gh-bot-auth
```

Check bot status:

```text
/gh-bot-status
```

Ask Pi to comment as bot, for example:

```text
Reply to PR comment 123456 as the bot: "Fixed in latest patch."
```

The extension injects tool guidance and a per-turn routing note so Pi uses `gh_bot` for visible GitHub comments/replies.

## Configuration

Custom bot config dir:

```bash
PI_GH_BOT_CONFIG_DIR=/path/to/gh-bot pi
```

Expected bot login:

```bash
PI_GH_BOT_EXPECTED_LOGIN=my-bot pi
```

When `PI_GH_BOT_EXPECTED_LOGIN` is set, `gh_bot` refuses mismatched browser auth and reports `gh: wrong-account`.

Disable automatic bash guard:

```bash
PI_GH_BOT_AUTO_GUARD=0 pi
```

The guard targets issue creation and review-thread reply commands. Context-dependent replies use prompt guidance. Normal comments/reviews, read-only `gh`, shell commands, and Git commands are not blocked unless the user explicitly requests bot attribution.

## Manual auth equivalent

```bash
mkdir -p ~/.config/gh-bot
env \
  -u GH_TOKEN \
  -u GITHUB_TOKEN \
  -u GH_ENTERPRISE_TOKEN \
  -u GITHUB_ENTERPRISE_TOKEN \
  -u GH_PROMPT_DISABLED \
  GH_CONFIG_DIR="$HOME/.config/gh-bot" \
  gh auth login --hostname github.com --web --clipboard --git-protocol https --skip-ssh-key

env \
  -u GH_TOKEN \
  -u GITHUB_TOKEN \
  -u GH_ENTERPRISE_TOKEN \
  -u GITHUB_ENTERPRISE_TOKEN \
  GH_CONFIG_DIR="$HOME/.config/gh-bot" \
  gh api user --jq .login
```

## Safety notes

- Normal terminal `gh` config is unchanged.
- Normal Pi shell `gh` and `git` remain your existing identity.
- Only the `gh_bot` tool and `/gh-bot-auth` use bot `GH_CONFIG_DIR`.
- Bot auth missing becomes explicit `gh: auth-missing`.
- Expected login mismatch becomes explicit `gh: wrong-account` and fails closed.
- You must provision the bot GitHub account yourself and grant it repo/org access where needed.
- Repository access still depends on the bot account permissions. If the bot is not a collaborator/member, it cannot comment in private repos.
- Set `PI_GH_BOT_AUTO_GUARD=0` if you intentionally want bash `gh` comments/reviews to use your personal identity.

## Development

```bash
npm install
npm test
npm run check
npm run pack:dry-run
```

## Publish checklist

This repo publishes with npm Trusted Publishing, not an `NPM_TOKEN` secret.

In npm package settings, configure GitHub Actions trusted publisher:

- owner: `adstastic`
- repo: `pi-github-identity`
- workflow file: `npm-publish.yml`
- environment: `npm`

Publishing is version-driven. On every push to `main` (and on `v*` tags), the workflow checks `package.json`:

- if `name@version` already exists on npm, it runs checks and skips publish
- if `name@version` is not on npm, it runs checks and publishes that version

Release by bumping `package.json` and pushing to `main`:

```bash
npm version patch
git push --follow-tags
```

You can still push a tag manually if needed:

```bash
git tag v0.1.1
git push origin v0.1.1
```

Workflow `.github/workflows/npm-publish.yml` runs `npm ci`, `npm run check`, then `npm publish --access public --provenance` only when the package version is unpublished.

Pi package discovery uses the `pi-package` keyword and `pi.extensions` manifest in `package.json`.