GitHub

Foxl Code works on your repositories through a GitHub App. Agents clone your repo into their VM, push a branch through Foxl, and open a pull request - they never get your personal credentials.

Connecting a repositoryCopiar el enlace a esta sección

1. Go to Repos in the sidebar.
2. Click Add source, then GitHub.
3. Install the Foxl Bot GitHub App on your account or organization.
4. Select which repositories to grant access to.
5. Your repos appear on the Repos page and in the repository picker of the message box.

Add source asks where your code lives before any sign-in page opens: GitHub, and GitLab or Bitbucket where Foxl Code offers them (on a phone the choice is a sheet, on a wider screen a menu under the button). The repositories from every source sit in one list, each with its host's mark, and a filter by host appears once you have more than one. A repository with the same name on two hosts is two rows, and Start task uses the one you pressed. A connected account that needs a new sign-in says so on its repositories and offers Reconnect. After you add an account or organization on GitHub's own page, Finish connecting on the Repos page brings its repositories in. The rest of this page describes GitHub.

Connecting GitHub adds an organization's installation to your Foxl account only when you are an active member of that organization; access to one of its repositories as an outside collaborator is not enough. Once you are removed from an installation, its tasks' files, terminal screen, typing and Resume stop working for you.

What the App can accessCopiar el enlace a esta sección

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:

No token a Remote task or the orchestrator holds can write your repository, and none 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.

How pushes reach GitHubCopiar el enlace a esta sección

A Remote task's pushes go through Foxl. Foxl reads which refs each push updates, checks them against the task, and only then relays the push to GitHub with a short-lived write credential that never leaves Foxl's server.

• A task that runs without you cannot push to the repository's default branch or push a tag, whatever a CI log, an issue or the repository itself tells the agent. That covers a task started from chat, the composer or the API, from an issue, Start an agent or an @foxl comment, by a schedule or the autonomous loop, a CI fix, a retry of any of these, and any of them reopened with Reconnect. Its work arrives as a branch and a pull request, and a branch the agent names itself is still pushed.
• A Remote terminal you open yourself is not restricted: from it you can push to the default branch and push tags. Its pushes go through Foxl too.
• A task on a machine you added (Settings > Code > Machines) follows the same rule once that machine's agent is version 0.3.2 or newer; re-run the installer on a machine whose row says an update is available. Until then it pushes directly, as before.
• A task on This computer pushes with your own GitHub credential (see On your own computer below).

Branches and pull requestsCopiar el enlace a esta sección

• 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, and if the coding agent already opened its own PR for the same commit, Foxl links that one instead of pushing a second branch. The PR 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. Neither does a run whose only change is a regenerated file - a package-lock.json npm created in a repository that had none, one where only its own version number or dev markers moved, or a sitemap whose lastmod dates were all reset - unless your request names that file or asks to pin dependencies, make installs reproducible or fix CI; the result names the files and says how to get a pull request for them anyway.
• Tasks from an issue - a task started from an issue written by the repository's owner, a member of its organization or a collaborator gets the issue as its specification, followed by the newest comments those people left on it (up to 10, each with who wrote it and when). An issue from anyone else is passed on as untrusted text, and other people's comments are left out.
• Title and description - the title is the agent's own commit message when it committed its work, otherwise the title of the issue the task was started from, otherwise the first line of what you asked for, and it is never cut in the middle of a word. The description links the task, says whether the repository's tests passed in the agent's sandbox, ends with the last part of the agent's own report, and for a task started from an issue says Closes #<issue>, so merging the PR closes it (with Post updates on the issue on, Foxl also closes it when the pull request that merged was one the coding agent wrote without that line; see Automation per repository). A commit Foxl makes carries that title (or, after the agent committed its own work, says it holds what the agent left uncommitted) and a Task: line naming the task.
• When the tests fail - the PR still opens, as a draft, with the failing test command and the end of its output at the top of the description, so the work can be reviewed rather than left on a branch. Auto-merge never merges a draft.
• Which tests run - with no setup, Foxl runs the test command it recognizes in the repository (npm test, make test or pytest), and the description says that this was its own choice and that other checks your CI runs did not run in the sandbox. To choose what runs, commit a .foxl/verify script at the repository root. Foxl runs it in place of the guess, after installing dependencies from your lockfile, with FOXL_VERIFY_BASE set to origin/<default branch> so it can check only what changed. Exit 0 passes. Exit 78 means "cannot run here" and, like a command that is not installed, counts as inconclusive rather than as a failure. Any other exit fails. A .foxl/verify that contains only comments says there is nothing to verify, and the description says so. It has five minutes, and it should not write files into the repository, since everything left in the checkout is committed.
• Named checks - to grade a change with several checks instead of one command, commit a .foxl/checks.json to the default branch, for example {"version": 1, "checks": [{"name": "unit-tests", "run": "npm test --silent"}, {"name": "lint", "run": "npx eslint .", "severity": "advisory", "paths": ["src/**"]}]}. It can list up to 12 checks. Each has a name (lowercase letters, digits, ., _ and -) and a run command, and can also set a severity, paths (globs such as src/** or **/*.ts; the check is skipped when no changed file matches), a cwd inside the repository, a timeout_s and inconclusive_exits (exit codes that mean "cannot run here", besides 78). A failing blocking check, the default, opens the pull request as a draft, as a failing .foxl/verify does. A failing advisory check is listed for the reviewer and does not. Each check runs with FOXL_CHANGED_FILES set to the path of a file that lists the changed files one per line, including new files the agent did not commit, and FOXL_REMOVED_FILES for the deleted ones. When the changes cannot be listed, FOXL_CHANGED_FILES_STATE is unknown and the list holds every file in the repository. The checks run one after another, blocking ones first, and share the same five minutes. Foxl reads the file from the default branch, not from the task's own changes, so a task that edits the file is still graded by the current list, and its description says so. The checks run the task's own code and scripts in its sandbox: they catch a broken change but are not a security boundary, so the pull request's own CI and review stay the gate. A file that is not valid opens the pull request as a draft that says what is wrong with it. The description and the task page list each check's result. With a .foxl/checks.json, .foxl/verify runs only when a check runs it, for example "run": "sh .foxl/verify".
• 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.

Merge trainsCopiar el enlace a esta sección

Ask the chat to combine several open pull requests of a repository ("merge #12, #15 and #20 together") and one coding agent merges them, in that order, into a new branch and opens one pull request. A train takes 2 to 20 open pull requests into the default branch, none from a fork and none that changes .github/workflows. Its agent can push only the train's own branch, never the original pull requests' branches, the default branch or a tag, and its pull request waits for you. When you merge it from Foxl Code it merges with a merge commit, whatever your merge method is, so GitHub closes each original pull request as merged.

The agent stops and says why on any conflict, unless the default branch's .foxl/train.json lists that file, and on a failing check. For example:

{
  "union": ["CHANGELOG.md"],
  "checks": ["node scripts/check-migration-numbers.mjs"]
}

union lists up to 20 files whose conflicts the agent resolves by keeping both sides, such as a shared changelog, and checks up to 10 one-line commands it runs on the combined code. Without the file, any conflict stops the train and no checks run.

Repository environmentCopiar el enlace a esta sección

Each repository can have an environment for your cloud tasks: on the Repos page, choose Environment in a repository's right-click menu, or follow the link at the foot of its automation settings.

• Setup script - runs with bash -e in the repository before the coding agent starts, with your secrets in its environment, for up to 10 minutes. Its time comes out of the task's maximum run time, and the agent is told how many minutes it has left. Its output is in the task log; if it fails, the task stops there and shows the script's exit code and its last lines. A service it starts in the background, such as a database, keeps running for the coding agent, and new files the script creates are left out of the pull request.
• Secrets - exported as environment variables to the setup script and the coding agent, and kept out of the task log. They are stored encrypted and are write-only: once saved, a value can be replaced or deleted but never shown again. The coding agent itself can read them, as it can any environment variable. A repository can have up to 32.

Both are yours alone: other people's tasks on the same repository do not get them. Neither applies to a task on your own machines, which runs in that machine's environment.

Repository notesCopiar el enlace a esta sección

A repository can keep one-line notes, so you do not have to correct the same thing on every task. When you approve a plan, request changes on a pull request or look at a finished task, Remember for owner/repo (folded away until you tap it) saves a short rule such as "Use pnpm, never npm", and every cloud task you start on that repository afterwards is sent it with its instructions. See, add, edit and delete them under Notes in the repository's menu on the Repos page.

Notes are yours alone: nobody else in the workspace sees them or gets them in their tasks, and Foxl never posts them to GitHub. A repository keeps up to 20 notes of up to 300 characters each. Saving the same note again keeps one, a 21st is refused rather than replacing an older one, and a note that looks like a password or a token is refused, since it belongs in Secrets. A terminal pane you reconnect keeps what Foxl Code knows about the repository (your notes, its project memory and recent failures).

Browsing what is openCopiar el enlace a esta sección

Work's Not started tab lists a repository's open issues and pull requests with nothing running on them yet, fetched only when you open it. Start an agent on an issue, close it, or diff and merge a pull request from there, so an issue can go from the tracker to a running agent without a browser trip. See Work.

Mention Foxl in a commentCopiar el enlace a esta sección

Write @foxl in a comment on an issue or a pull request in a connected repository:

• @foxl review on a pull request runs Foxl's read-only reviewer on its latest commit (see Review on approval). It posts its findings as a review on the pull request and never merges. A review asked for in everyday words does the same, such as "@foxl, review this please", "@foxl please review" or "Can you review this? @foxl"; a comment that asks for work as well, such as "please review the error handling and fix the null check", is read as a request for work instead, as below.
• @foxl <what you want> on a pull request a Foxl Code task opened passes your comment to that task: to its agent if it is still running, or by reopening the task with your comment as its next step. Only the person who started the task can do this.
• @foxl <what you want> on an issue starts a task with the issue and your comment as its brief. If a task of yours is already working on that issue, your comment goes to it instead. If another member's task is working on it, Foxl replies with a link to that task and starts nothing, since only the person who started a task can pass it a comment.

On a pull request Foxl did not open, only @foxl review is available: Foxl works on its own branch and does not push to a branch someone else opened.

Foxl acts only for a comment author who is linked to Foxl, is a member of the installation and can push to the repository. It adds an eyes reaction to the comment when it picks it up and replies with a link to the task, or with the reason when it does not act. A mention inside a quote, inline code or an HTML comment (which GitHub does not show), an edited comment and a comment from a bot are ignored. A task started from a comment counts toward your in-progress task limit and spends your credits like any other task.

Automation per repositoryCopiar el enlace a esta sección

On the Repos page, the automation button on a repository (or Automation in its right-click menu) holds three settings. They are yours, not the whole team's: the first two spend your credits, and the third acts on your tasks:

• Issues you open. By default every issue you open in a connected repository starts a task. Choose Only issues labeled foxl to start one only when you open an issue with the foxl label or add that label later (whoever adds the label is who the task belongs to), or No issue starts a task to turn it off. Either way you can still start a task from Work, or by mentioning @foxl in the issue.
• Review every pull request when it opens. Off by default. When it is on, Foxl's read-only reviewer runs on each new pull request in the repository that a Foxl Code task did not open (and on a draft when it is marked ready for review), on your credits, and posts its review. It never merges, and it skips pull requests opened by bots.
• Post updates on the issue. Off by default, because it writes in your repository. When it is on, a task of yours that was started from an issue (with Start an agent, by issue intake or the foxl label, or by an @foxl comment) comments on that issue once per run when its pull requests are open, with their numbers, the branch and a link to the task, so the people watching the issue are notified. Foxl checks the issue each time a pull request from a Foxl task on it closes. If by then the work has merged into the default branch, no other pull request from a Foxl task on the issue is still open and ready for review, and no other open pull request (yours, a teammate's or an older Foxl one) mentions the issue, Foxl closes the issue as completed, with a comment saying so, but only when no merged pull request closes or mentions the issue itself: a Closes #<issue> is left to GitHub, and a deliberate Refs #<issue> keeps the issue open. If another open pull request mentions the issue at that check, the issue stays open for you to close: Foxl does not check again when that pull request closes. A pull request closed without merging never counts as the work being done. Foxl closes an issue at most once: if you reopen it, Foxl leaves it open, and reopening does not start a new task. It costs no credits.

The repository's row shows a badge when issue intake or the reviewer setting is not the default.

WebhooksCopiar el enlace a esta sección

Foxl listens for issues, pull_request, pull_request_review, check_suite, workflow_run, issue_comment, pull_request_review_comment, 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, and answer @foxl in comments. Incoming webhooks are verified with an HMAC signature, and a PR is matched back to its task by the exact branch suffix.

A comment that does not contain @foxl is answered with a 200 and dropped without being parsed or stored; only a comment that mentions Foxl is read, and its text becomes the task's instruction. An event Foxl does not act on at all is 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 is commit_comment, check_run and push, which the App is still subscribed to.

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 computerCopiar el enlace a esta sección

A task or chat turn that runs on your computer in the Foxl desktop app (This 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. A machine you add in Settings > Code > Machines works with the GitHub App instead, and its pushes go through Foxl from machine agent 0.3.2 (see How pushes reach GitHub). See On your own computer.