house / GitHub Agent Identity

---
name: github-agent-identity
description: >
  Use when a coding agent (Claude Code, Codex) should act on GitHub under its
  own bot account instead of the human's: commits, pull requests, comments,
  reviews and labels. Sets up one GitHub App per agent, mints one-hour tokens
  per command, configures Claude Code and Codex, and checks for the silent
  fallbacks that put the human's name on agent work.
license: MIT
compatibility: Requires Node 20+, git and the GitHub CLI (gh). Written for github.com; set GHAPP_API_URL for GitHub Enterprise Server.
category: git
tags: [github, github-app, identity, accountability, claude-code, codex]
agents: [claude-code, codex]
metadata:
  author: jack-arturo
  version: "1.0.0"
capabilities:
  network: true
  filesystem: readwrite
  tools: [Bash, Read, Edit, Write]
resources:
  - path: references/app-setup.md
    type: file
  - path: references/claude-code.md
    type: file
  - path: references/codex.md
    type: file
  - path: references/troubleshooting.md
    type: file
  - path: scripts/mint-token.mjs
    type: file
  - path: scripts/ghapp
    type: file
  - path: scripts/verify.sh
    type: file
---

GitHub Agent Identity

Give each coding agent its own GitHub account, so every commit, pull request,

comment and label shows which tool did it. The human's name then appears only

on what the human did, usually the merge.

Each agent gets a GitHub App. The App's private key stays on the machine.

Before each GitHub command the agent trades the key for a token that lasts an

hour, and GitHub records the action as <app-name>[bot].

When to use this skill

• Setting up a new agent identity, for yourself or a teammate.
• A PR, comment or commit from an agent shows up under a person's name.
• Adding Claude Code or Codex to a repo that already uses agent identities.
• Reviewing whether an existing setup still works (run scripts/verify.sh).

Skip it for CI bots. GitHub Actions already has github-actions[bot].

The moving parts

Nothing secret goes into an environment variable. Agent harnesses filter and

log environments in ways that are hard to predict, so the key stays in a file

and the token exists only inside a single ghapp call.

Setup

Work through these in order. Each step links to the detail.

1. Create the App, install it on the repos, save the key, and write the profile. references/app-setup.md
2. Copy the scripts to ~/.local/bin: mint-token.mjs, ghapp, verify.sh.
3. Get the author email with mint-token.mjs --bot-email. The number in it is the bot's user id. It is not the App id.
4. Wire up the agent: Claude Code or Codex. Both need the three environment variables and one instruction line telling the agent to use ghapp for GitHub writes. Codex also needs network access in its sandbox.
5. Verify from inside the agent: ask it to run verify.sh owner/repo. Every line should say PASS.

Daily rules for the agent

• Use ghapp for anything that writes to GitHub: ghapp pr create, ghapp pr comment, ghapp issue create, ghapp pr edit --add-label. Plain gh acts as the human.
• Never export GH_TOKEN. An expired exported token makes gh fail instead of falling back, and a fresh one leaks into every later command.
• Leave GIT_COMMITTER_* alone. The agent is the author and the human's machine is the committer, which is what those two fields mean.
• When several people or tools share one App, name the tool in the PR body.

When something is off

Most failures don't raise an error. GitHub completes the action and puts

the human's name on it, so check the result rather than waiting for an

error. The symptom tables are in

references/troubleshooting.md.

Quick checks:

ghapp pr view 123 --json author --jq .author.login   # app/<name>, not a person
git log -1 --format='%an <%ae>'                      # <name>[bot] <id+name[bot]@...>
verify.sh owner/repo                                 # all PASS

Why it exists

Every agent I run used to work through my GitHub login. Claude Code opened PRs as

me, Codex commented as me, AutoJack labelled issues as me. Scroll a PR timeline

and it looked like I'd been very busy at 4am.

That's fine until you need to know which tool did something. **The avatar is the

cheapest audit log there is**, and I was throwing it away.

So each agent got its own GitHub App: claude-jack, autojack-bot,

cursor-jack, gemini-jack. Codex already posts reviews as

chatgpt-codex-connector[bot]. Now a PR reads like a sign-in sheet. The bot wrote

it, Codex reviewed it, and the only line with a human on it is the merge. There's

a walkthrough of one real PR on AutoJack Labs.

History

1.0.0

Pulled out of AutoHub, where the same thing runs through a hub-specific token

helper and a gh shim for the PR babysitter. This version has no AutoHub parts.

A dependency-free Node script mints tokens, ghapp wraps gh, and verify.sh

checks the result. Claude Code and Codex setup are included because that's what

the team runs.

How Jack actually uses it

One App per agent. The key sits in ~/.config, the agent's settings name the

profile, and the agent's instructions say ghapp for anything that writes. Tokens

last an hour and get minted per command, so a six-hour session never trips over an

expired one.

The part that took longest wasn't the App. It was finding the ways it

quietly falls back to my name. An agent that forgets ghapp opens the PR as me.

A missing author email makes me the author. A commit email with the App id

instead of the bot's user id gets no avatar. None of these throw an error,

which is why verify.sh exists.

What it is not

Not a permissions sandbox. The App's permissions limit what its token can do,

but the agent still runs as you on your machine. Not for CI either, where

github-actions[bot] already has you covered.