Source control

GOAT integrates with GitHub, GitLab, Forgejo, Gitea, Bitbucket, Azure DevOps, and GitCafe to clone and publish repositories, create pull requests, and review changes.

Review turn changes

A turn’s changed files and diff show only the turn’s own work. When a turn pulls, merges, or rebases, the files Git brought in are left out. A file stays in the list when the turn edited it, committed it, or fixed a conflict in it. Use the branch comparison to review everything that changed against your base branch. Restore still returns the complete saved workspace.

Fetch a branch from an SSH worktree

For a thread started with Worktree on SSH, open it in the desktop app and choose Git actions → Fetch branch to this device, or find the action in the command palette. Keep the host saved and enabled in Settings → Connections.

The branch is fetched into the original repository on this device. The result shows refs/remotes/goat-ssh/<alias>/<branch>. Fetching leaves your current branch, staged changes and working files in place. It brings back committed work; commit changes on the remote thread before fetching if you need them locally.

In a terminal in the original repository, inspect the exact ref shown in the result:

git log --oneline "HEAD..refs/remotes/goat-ssh/<alias>/<branch>"
git diff "HEAD...refs/remotes/goat-ssh/<alias>/<branch>"

Replace <alias> and <branch> with the values from your result. You can then choose how to merge or cherry-pick the commits. Fetching itself does not merge them.

If this device no longer has the original project at its original location, fetching is refused. Reconnect this device or enable the saved SSH environment when the action is disabled. The thread stays on its remote host after fetching.

Connect an account

Install Git and configure authentication on the machine running your GOAT server. For a remote environment, do this on the remote machine. After signing in, open Settings → Source control and choose Rescan.

GitHub

GOAT talks to GitHub’s API directly and only needs a token. Any of these works, in this order of precedence:

1. A token saved in Settings → Source control → GitHub. It is kept in the server’s secret store, and works without the GitHub CLI.
2. GH_TOKEN (GH_ENTERPRISE_TOKEN with GH_HOST for GitHub Enterprise Server) in the server’s environment.
3. GitHub CLI 2.81.0 or newer, signed in with gh auth login.

If gh is signed in to several accounts or hosts, expand GitHub in the same place to pick the account each host uses or turn a host off. A saved token or GH_TOKEN takes precedence over that choice; a host turned off stays off either way.

For GitHub Enterprise, sign in with gh auth login --hostname YOUR_HOST. GOAT treats a custom server name as GitHub once it has a credential for that host.

Forgejo and Gitea

Install Forgejo CLI (fj) or Gitea CLI (tea) 0.16 or later on your GOAT server. Sign in with fj --host https://your-server auth add-token or tea login add. Repeat for each server you use, including Codeberg.

GOAT prefers a matching fj login and falls back to tea when fj is unavailable or has no login for that server. Once an account is selected, failed actions stay on that account. Settings shows the detected CLI. Forgejo and Gitea share one integration entry. Servers hosted under a URL subpath, such as https://example.com/forgejo, use tea because fj 0.6 does not preserve the subpath when checking its account.

When cloning or publishing, use a full repository URL to select a specific server. You can use owner/repo when only one fj server is configured, or with your default tea login when fj is unavailable or unconfigured. With multiple fj servers, use the full URL. If you have multiple tea accounts on one server, select one with tea login default <login-name>. Git push and clone also need Git credentials or an SSH key for that server.

GitLab

Install GitLab CLI, then sign in:

glab auth login

Bitbucket

Open Settings → Source control, expand Bitbucket, and enter one of:

• Access token: a token created for one repository, project, or workspace. It can only reach what it was created for.
• Atlassian account email and API token: an Atlassian API token for your account. It can reach every repository you can. Give it read/write access to repositories and pull requests, plus user read access (read:user:bitbucket).

A field saves when you leave it, and applies right away. The access token wins when both are saved. Credentials are saved on the environment’s server, so select a remote environment to configure it. Saved tokens can’t be viewed again; enter a new one to replace it, or choose Remove to clear everything saved for Bitbucket.

If no credentials are saved, GOAT falls back to these variables in the server’s environment. Restart the server after changing them:

export GOAT_BITBUCKET_ACCESS_TOKEN="your-access-token"
# or
export GOAT_BITBUCKET_EMAIL="you@example.com"
export GOAT_BITBUCKET_API_TOKEN="your-token"

For a background service, put these KEY=VALUE entries in service.env under GOAT home, then run goat service restart. Service installation and updates preserve that file.

Azure DevOps

Install Azure CLI, add the DevOps extension, and sign in:

az extension add --name azure-devops
az login

GitCafe

Install the GitCafe CLI and sign in:

bun install -g @gitcafe/cli
cafe auth login --host https://git.cafe/api

Alternatively, open Settings → Source control, expand GitCafe, and enter a token. It is kept in the server’s secret store, applies right away, and is used before CAFE_TOKEN and the cafe login. Or set CAFE_TOKEN in the server’s environment and restart it. Both tokens are only sent to git.cafe; CAFE_TOKEN follows CAFE_HOST if you set it. Repositories on staging.git.cafe need their own login with --host https://staging.git.cafe/api.

Line comments are not available for GitCafe pull requests yet. Merging a stack lands it through GitCafe, and updating a branch restacks the layers above it.

Start, clone, or publish a project

To start from nothing, choose New project in the command palette (Cmd/Ctrl+K), or New project under Add Project on any client, and type a name. GOAT makes a Git repository in ~/.goat/projects (the projects folder of your GOAT data directory) with a README, an icon, and a first commit, then opens a new thread in it. Until the project has a thread, new threads work in its folder, even when your default is a new worktree. The folder is named after the project, like pinball-stats for “Pinball Stats”. Turn on Create private repository on GitHub to also publish it. If Git has no name or email on that machine, the project is created without the first commit.

Use Add Project in the command palette (Cmd/Ctrl+K) to clone a repository. Choose a hosting provider or paste a Git URL, then choose where to save it. The project opens right away while the clone runs in the background: you can write your first prompt, and sending waits until the files are in place. A toast tracks progress and lets you cancel; if the clone fails, retry it from the toast or from the banner above the composer. When the host refuses the machine’s SSH key, GOAT clones over HTTPS with Git’s credentials for that host instead, and the project’s remote uses the HTTPS URL.

For a local Git repository without a remote, Publish Repository creates a hosted repository, adds it as origin, and pushes your commits. If there are no commits yet, it creates the remote; make your first commit before pushing.

Create a pull request

Use a thread’s Git actions to commit, push, and create a pull request. GOAT can generate commit messages, review titles, and descriptions from your changes. Descriptions also draw on the work in the thread, including the checks it ran.

An existing fork PR can appear beside the branch even if you pushed without setting an upstream. If its badge is missing because several remotes hold that branch, set the branch’s upstream to the intended remote with git branch --set-upstream-to=<remote>/<branch>.

Choose the writing style and model in Settings → Source control. Repository conventions uses the project’s instructions and recent commit subjects.

Review and merge

Open Pull requests to review changes and comments, request reviewers, check out a branch, or merge. You can edit review titles and descriptions and your own comments where the host allows it. GitLab calls these merge requests.

For a fork whose checkout also has an upstream remote, the list shows pull requests from the fork’s own origin repository. Turn on Include upstream repos in the filters to add the repository it was forked from.

Ask an agent to edit a PR, comment, submit a review, reply to or resolve a review thread, manage reactions, labels and reviewers, or change its state through GOAT’s MCP tools. The repository must be a project in the connected environment. Outside MCP clients need the source-control:write grant; read-only and reduced operate access cannot write. Plan-mode threads cannot write, and goatclaw profiles need pr.open, with pr.merge for merge and close. Comments, reviews and replies require a retry key. If a write’s outcome is uncertain, the agent checks activity and tells you when it cannot confirm the result; a partial GitLab review or unconfirmed approval does not count as complete. Merge requests act on the host’s current head and may be queued; use branch protection when a merge must require a particular head.

On mobile, Pull requests lists reviews across your connected environments. Open a review to read its description, activity, commits, and changed files. Line comments stay as drafts until you submit the review. Work on PR opens a chat with the review attached; sending the first message prepares a worktree from the review’s branch.

Previously loaded lists, review details, guides, and diff pages remain readable on mobile without a connection, including after restarting the app. Saved content refreshes when the environment reconnects; submitting changes requires a connection.

Enable Remove agent credits when merging in Settings → Source control to remove recognized agent co-author and generated-by lines from GitHub merge and squash commit messages. Human co-authors stay credited. The setting is off by default and projects can override it. It also applies to auto-merge, but not merge queues or native stack merges. Original commits keep their messages, so merge and rebase can still retain agent credits in those commits.

On web and desktop, hold Shift in the GitHub pull request list for quick actions. To close several, press Close, drag across the rows in the same group, and release. Press Escape before releasing to cancel. Failed closes stay in the list so you can retry them.

GitHub, GitLab, and Azure DevOps support auto-merge while checks are outstanding. GitHub also supports approving waiting fork workflows and opening a revert pull request for a merged change.

Pull request sharing is off by default. In Settings → Connections → Pull request sharing (Pull request routing under Environments on mobile), choose Read PRs or Read and act for each environment you trust to share its source control access. Enable both the original environment and the environment answering its requests on this client. Read and act can use broader permissions than the original environment’s credential; only enable it for environments you control and trust. Changing a saved endpoint or removing an environment clears its permission.

Review details, linked PR status, and permitted review actions can then use another connected environment signed in to the same account on the same host. Each needs a project on that host. A connected local environment is preferred for actions and can answer slow or failed reads. Browsers and mobile clients need a paired environment to use its GitHub credentials. Credentials stay on their machines. Previously verified credentials remain usable for routing for ten minutes during a GitHub outage; new credentials must be verified first. An action with an uncertain result is never automatically retried elsewhere. Listings, diffs, and checkout or PR creation from Git actions continue to use the project’s environment.

For Azure DevOps, use the host website to change comments. Bitbucket does not support reopening a declined pull request.

Review guides

Review guides are in beta. Turn on Review guides in Settings → Source control to add the Guide tab to pull requests on that server. On mobile, move between stops with Next and the back button; a stale guide offers a rewrite and hides excerpts that no longer match the current change.

The Guide tab gives you a tour of a pull request without reading it line by line: stops through the change in reading order. Each stop points at the lines worth reading, and a stop marked Look closely has a call only a maintainer can make. Mechanical changes such as renames and snapshots are grouped at the end, and every changed file appears somewhere on the tour. Conversations already resolved in review are left out. For a pull request in a stack, the guide covers that layer only, and may point out what a lower layer introduced or what a higher one uses.

Choose Write guide to have the review guide model from Settings → Source control read the change in a temporary checkout; without one set, the source control writer model is used. Nothing in the checkout is changed, and a large pull request takes a few minutes; you can go elsewhere in the app. On web, you are told when the guide is ready; on mobile, return to the guide to check its progress. Claude and Codex can write guides. The guide is kept for everyone using this server. To write it again, for example after a push or after changing the model or instructions, choose Rewrite guide from the pull request’s ⋯ menu.

On web, while reading a stop, select lines in an excerpt to add a comment to your review or ask an agent about them; comments wait with the ones from the Code tab until you send the review. Choose a suggested question, or Ask about this stop, to open a thread that already knows which stop you are on. Finish review on the last stop opens the review with everything you collected.

Agents can write guides too: ask one to prepare guides for a set of pull requests, and it starts them for you. Each is read through the project whose checkout has that repository.

To shape guides to your taste, write Review guide instructions in Settings → Source control, such as what to show first or what to skip; projects can override them. They change emphasis and ordering, not the guide’s layout or which files it covers.

Mark files as viewed

Tick a file off in the Code tab once you have read it and it collapses; the toolbar keeps a running count. A tick belongs to the pull request rather than to a commit, so scoping the tab to a single commit keeps them. A file pushed to after you cleared it comes back marked Changed.

On GitHub these are GitHub’s own viewed marks, so a review carries between GOAT and github.com in either direction. Forgejo, GitLab, Bitbucket, and Azure DevOps expose no record GOAT can read, so the server you are connected to keeps them instead: they follow you across the apps connected to that server, but the host’s own site will not show them, and the count reads viewed in GOAT.

On mobile, open a changed file and mark it viewed from its header. Viewed files collapse, and their marks follow the same rules as on web and desktop.

Troubleshooting

• Not authenticated: run the provider’s login command on the server, then rescan. For Bitbucket, check the credentials saved in Settings → Source control, or confirm the running server received the environment variables.
• GitHub sign-in cannot be verified: update GitHub CLI to at least 2.81.0, or save a token in Settings → Source control.
• Push fails despite a connected account: check the Git remote’s credentials. SSH and HTTPS remotes can require separate setup from the hosting provider’s API access.
• A review cannot load: open it on the host website while resolving connectivity, permissions, or rate limits.

Linked pull requests

A thread can hold several pull requests, including reviews from another repository on the same host. Use Link pull request in the command palette or Linked pull requests panel, or right-click a pull request link in the conversation. Creating a pull request from Git actions links it automatically, and so does an agent creating one with gh pr create or glab mr create. Agents can link other pull requests with goat_call {path:"pull_request.link"}. Agents can also read any pull request in a repository that is a project here, fresh from its host: pull_request.read returns what the pull request view shows, and pull_request.checks only its checks.

Use Link this PR in a branch-detected badge’s tooltip to keep it with the thread. From a review on the Pull requests page, Link to thread lets you search for an active thread. The review header also lists the threads that link to it, including archived threads, so you can return to their context.

Thread badges show a stack’s layer count or the current review number with a count of additional links. Clicking a badge with more than one review opens the Linked pull requests panel. On mobile, the Git overview lists linked reviews and their stacks; tap a review to open it. Linking and unlinking are available in the web and desktop clients.

The Linked pull requests panel lists every review and groups stacks. Unlink a review from its row menu. An unlinked stack layer stays out of later syncs. Open linked reviews refresh on the server; closed reviews refresh periodically so reopening one on the host is detected. Merged reviews refresh when requested. A settled thread’s reviews stop refreshing until you unsettle it. With Auto-settle merged threads enabled, a thread can settle after every linked review is terminal. An open or unsynced link keeps it active.

GOAT automatically watches open pull requests that a thread creates or its agent links, unless you turn off automatic watching. Automatic watches can wake the agent without keeping the thread in Working. Ask the agent to watch, monitor, or babysit a pull request to make the watch explicit with goat_call {path:"pull_request.watch"} and keep the thread working between wakes.

The server checks every two minutes. By default, failed checks, passing required checks, and other people’s comments or reviews wake the agent. Your own comments do not. Bot comments are ignored unless the bot is listed in Bots that count as people. Merge conflicts do not wake a thread idle for more than 3 days. In Settings → Organization, choose React to wake the agent immediately, Keep as context to record an update on the timeline and include it with the next wake without starting a turn, or Ignore to drop it. You can choose separately for failed checks, passed checks, human feedback, bot feedback, and conflicts, and adjust automatic watching and the conflict idle limit.

To start or stop watching yourself, use the row menu in the Linked pull requests panel. In the thread details card, click a watched pull request’s eye to stop it. Asking the agent to stop calls goat_call {path:"pull_request.unwatch"}, which stops either an automatic or explicit watch and keeps the PR linked. Watching also ends when the PR merges or closes, after 10 wakes in a row that bring only comments, after 8 failed reads in a row, or when you press Stop, settle, or archive the thread. A rate limit only pauses watching. Unsettle the thread before starting a new watch. Watching a pull request again does not repeat check or conflict news its last watch already reported; unlinking the pull request clears that. Subagents cannot watch pull requests; the thread that delegated to them does.

An explicitly watched thread does not auto-settle. It appears in Priority, at the top of Activity on web and desktop and at the top of the thread list on mobile. Mark all as read acknowledges unread completions without stopping a watch. Agents stop watching when they hand the work back to you.

Cross-repository links use a project on the same host. Azure DevOps reviews require a project checked out from the matching organization and repository.

GitHub stacks

The Pull requests page shows each PR’s position in its GitHub stack. Open the stack badge in a review to navigate its layers. Merge stack submits the selected pull request and every unmerged layer below it to GitHub together, respecting branch rules and merge queues. The confirmation shows the scope and merge strategy. GitHub rebases the remaining stack after merging.

Rebase stack updates remote branches from bottom to top without changing your local checkout. It can rewrite history and restart checks. If a layer fails, earlier updates remain; resolve that layer before retrying. GitHub may require manual conflict resolution after a lower layer is amended, even when its changes look independent. Stack actions require an environment that supports them.