GitHub
Connecting repositories, the GitHub App, branches, and pull requests
GitHub
Foxl Code works on your repositories through a GitHub App. Agents clone your repo into their VM, push a branch, and open a pull request - they never get your personal credentials.
Connecting a repository
- Go to Repos in the sidebar.
- Click Connect GitHub.
- Install the Foxl Bot GitHub App on your account or organization.
- Select which repositories to grant access to.
- Your repos appear on the Repos page and in the repo picker at the left of the Tasks header.
What the App can access
The GitHub App holds broader permissions than any single task ever receives. Every token minted for a task is narrowed at the mint, and GitHub enforces the narrowing at its own edge:
| Token for | Contents | Pull requests | Issues | Checks | Metadata | Actions |
|---|---|---|---|---|---|---|
| The coding agent | Write | Write | Write | Read | Read | - |
| The orchestrator | Write | Write | Write | Read | Read | Write (to trigger a build) |
| The reviewer | Read | Write | Write | Read | Read | - |
No token carries administration or workflows. An agent cannot change repository settings, and a push that touches .github/workflows/** is refused by GitHub with a 403 naming the permission - a deliberate limit on an agent branch, not a bug. The reviewer's token cannot push at all.
Tokens are minted per task, scoped to the one repository the task is in (GitHub answers 404 for anything else), narrowed as above, and expire after one hour. They are passed to the agent's machine for that task only and are never stored.
Branches and pull requests
- Branch name - each task pushes to a deterministic branch,
foxl/<last 12 characters of the task id>. Because it is deterministic, a retry re-pushes to the same branch instead of creating a duplicate. - Pull request - when the agent finishes, it opens a PR from its branch into the repository's default branch. If a PR for that branch already exists, the agent recovers and reuses it rather than failing. The PR is titled after what you asked for and contains only the agent's changes - Foxl's own instructions file is written for the assistant but stays out of the commit - and a task where the agent did nothing opens no pull request at all.
- Issues - when the orchestrator plans multi-PR work, a checkbox can open a GitHub Issue so the work is tracked in your repo as well as in Foxl.
Browsing what is open
Work's Backlog tab lists a repository's open issues and pull requests with nothing running on them yet, fetched only when you open it. Solve, Decline, Diff and Merge work from there, so an issue can go from the tracker to a running agent without a browser trip. See Work.
Webhooks
Foxl listens for issues, pull_request, pull_request_review, check_suite, workflow_run, the installation events, and organization / membership (used to keep an organization's member access in step), so it can advance a Task Document's checkboxes as PRs are opened, checked and merged. Incoming webhooks are verified with an HMAC signature, and a PR is matched back to its task by the exact branch suffix.
An event Foxl does not act on is answered with a 200 and dropped before its body is read: only the delivery id, the event type and the sending address go to the server log, and nothing is stored. Today that includes the comment events (issue_comment, commit_comment, pull_request_review_comment) plus check_run and push, which the App is still subscribed to - so a comment on your issue or pull request is delivered to Foxl, signature-checked and discarded unread. Unsubscribing those events at the App is the pending fix; until then the text of a comment is never parsed or stored, but the delivery itself does reach Foxl.
pull_request_review is what powers the approval gate: when you approve a pull request, Foxl can run an independent adversarial review of the diff before anything merges. See Review on approval.
On your own computer
A task or chat turn that runs on your computer uses your own GitHub credential - gh auth login, your git credential helper, or FOXL_CODE_GITHUB_TOKEN - and never an installation token. The tools confine it to the repository you have selected, and if no credential exists the refusal says so. See On your own computer.