pi-github-identity

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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`.

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:

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:

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.
Per-turn prompt note: every user turn gets that routing rule; all other GitHub actions use normal tools and identity.
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:

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:

PI_GH_BOT_AUTO_GUARD=0 pi

Provision the bot account

Before using the extension:

Create/register a separate GitHub account for the bot.
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
Run /gh-bot-auth and authorize that bot account in the browser.
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:

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:

pi install npm:pi-github-identity

From GitHub:

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

From local checkout:

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

Development symlink:

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:

/reload

Usage

Authenticate bot:

/gh-bot-auth

Check bot status:

/gh-bot-status

Ask Pi to comment as bot, for example:

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:

PI_GH_BOT_CONFIG_DIR=/path/to/gh-bot pi

Expected bot login:

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:

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

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

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:

npm version patch
git push --follow-tags

You can still push a tag manually if needed:

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.