GitHub
Connect GitHub for agents to read the repositories you choose, and to work in them from a sandbox as you.
Agents read the repositories the person who connects GitHub can reach among those Personal Agent Proxy's GitHub App is installed on, and, from a sandbox, clone them, push to them and use GitHub's API as that person, with what you allow. Repositories stay on GitHub; nothing is copied.
Connect GitHub
Install the app on GitHub
Open the app's page on GitHub and install it on your account or an organization, choosing all of its repositories or only some. The repositories you choose are the ones agents can reach, and you can change them any time under Settings, Applications on GitHub.
Sign in with GitHub
Open Connections and permissions, then Add connection, and Sign in with GitHub, and authorize the app. Signing in alone grants no repositories: the connection's page opens on Repositories, which lists what agents reach, account by account as the app is installed, with the way to change it on GitHub, or says the app is installed nowhere you reach yet, with a button to install it.
Review the defaults
A new GitHub connection gives every agent Read repositories, and nothing that changes anything. Turn on what agents may change for every agent on the connection's page, or only for one agent on the agent's page.
What agents can do
- Read repositories lists the repositories the app is installed on and opens one, with its description, visibility, default branch, language and when it was last pushed to. From a sandbox, it also clones and fetches them, and reads anything through GitHub's API.
- Push to branches pushes to any branch but the repository's default one, and pushes tags, from a sandbox, with git or through GitHub's API.
- Push to the default branch pushes to the repository's default branch, such as
main, without a pull request: committing to it, resetting it or deleting it. It only counts with Push to branches. Without it, an agent pushes a branch of its own and opens a pull request instead. - Open pull requests and issues opens, edits, closes and reviews pull requests, opens and edits issues, comments on both, and labels and assigns them.
- Merge pull requests merges them, or has GitHub merge one once its checks pass.
- Change anything else on GitHub is whatever else GitHub's API changes: a repository's settings, releases, workflow runs, forks, labels, webhooks and the like.
All but Read repositories are off unless you turn them on. Each is also bounded by what the app may do on GitHub and by the repositories you installed it on: an agent can never do more on GitHub than the app and your own account can.
Working in repositories from a sandbox
An agent works in a repository from a command run with pap turned on in one of its
sandboxes, with two commands of pap's:
pap gitis git, signed in as you:pap git clone https://github.com/acme/demo(orgit@github.com:acme/demo.git), thenpap git pushandpap git fetchin the clone. Commits made withpap git commit, and anything else of git's that makes commits or tags, are made as your GitHub account, with GitHub's noreply address for it rather than your own email, unless the command setsGIT_AUTHOR_NAMEand the like itself.pap git clonewrites that name and address into the clone's own config asuser.nameanduser.email, so commits made there with plain git are yours too; nothing of the sign-in is written.pap ghis GitHub's own command line tool, signed in as you:pap gh pr create,pap gh issue list,pap gh api …. The git it runs itself, as forpap gh repo clone, ispap git.
With several GitHub connections, the agent names one before the command: pap --connection <id> git … or pap --connection <id> gh …; without it, pap uses the agent's only one, and refuses,
listing them, where it has several.
Plain git and gh in the sandbox stay signed out, and your GitHub token never enters it: every
request of pap git and pap gh goes through Personal Agent Proxy, which checks it against what
the agent may do, adds your token on its way to GitHub, and passes GitHub's answer back. Nothing
is written to the repository's or the sandbox's git or gh configuration: a clone keeps
https://github.com/… as its remote, and pap gh gives gh a configuration of its own that is
removed when it exits.
Reading through the API needs Read repositories, as a GraphQL query does. A change needs the action above that covers it, told by the request's path, or for a GraphQL mutation by the mutations it runs; one none of them covers needs Change anything else on GitHub. A push, with git or through the API, asks GitHub which branch is the repository's default to tell whether it needs Push to the default branch; one whose branch can't be told, such as a ref moved through GraphQL, needs it. A request the agent isn't allowed is refused, saying which action it needs, and doesn't reach GitHub.
In the activity log
Every request is in the activity log under the agent's task, shown as from a sandbox, with the repository where it names one: a fetch or clone, as "Fetched acme/demo"; a push with the branches it updates, as "Pushed to acme/demo: fix-login"; and each API request by its method and path, as "POST /repos/acme/demo/pulls", a GraphQL one with its operation. Refusals are there too, and requests GitHub turned down for the sign-in, or couldn't answer.
Not supported yet
- Git LFS.
- Uploading release assets, which GitHub takes at another address than its API:
pap gh release uploadand the like are refused, saying so. - A git alias for
push,fetchor another command that reaches GitHub: run the command itself. pap gh pr createpushing the branch for you, which gh only offers when it can ask: push it withpap git push -u origin <branch>first.
Sharing a GitHub connection
A GitHub connection shared with everyone, or with some members, is used by their agents as yours is: what they push, open and comment on GitHub shows as made by your account. Share it with that in mind, and turn on what changes things only for the agents you mean to.
Self-hosting
Hosted Personal Agent Proxy has its own GitHub App. A self-hosted server needs one of its own:
register a GitHub App under your account's or organization's developer settings, with
<APP_URL>/api/connections/github/callback as a callback URL, Expire user authorization
tokens on and Request user authorization (OAuth) during installation off, no webhook, and
the repository permissions Contents, Pull requests and Issues read and write and Metadata read.
Then set its client id and a client secret as GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET, and
its name as it is in its address, github.com/apps/<slug>, as GITHUB_APP_SLUG
(Environment variables), which is where people are sent to install it.
What agents do through pap gh beyond that, such as running workflows, or pushing changes to a
repository's workflow files, needs the app's matching permission too, Actions or Workflows; GitHub
refuses it otherwise.