# Source control integrations Source control records how project files change over time and makes it possible to review, restore, and share those changes. It is useful for code, analysis scripts, manuscripts, configuration, and other text-based research material; you do not need to be a software developer to use it. Scient can connect a Git project to its hosting provider so you and the AI can create branches, publish changes, and review them without leaving the app. Source control is optional. An ordinary local folder can still be a Scient project without Git or a hosted repository. [No project conversations](./thread-sidebar.md#threads-without-a-project) use plain scratch folders. They have no Git branch controls, checkpoints, or turn diffs. ## 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. On web and desktop, open the Diff pane source picker and choose **Commits** to review one local commit at a time. The list shows the newest 100 commits in the branch comparison. A merge commit shows its changes against its first parent. A commit link from a supported code host opens in the Diff pane when the thread's repository has that commit locally, on any branch. Otherwise a pull request commit link opens the pull request. Other commit links follow your **Open links in** setting; on web, when that opens a new tab, Scient first shows an **Open link** button. Command/Ctrl+Click always opens the link in your browser. Commit links follow the **Open pull requests in Scient** setting in **Settings → Diffs & pull requests**. ## Overleaf **Settings → Source Control → Overleaf** sits beside the hosting providers. It holds the Overleaf Git token (**Create a token on Overleaf ↗**, **Save**, **Remove**) and every folder on this computer linked to an Overleaf project, by project, each with its state, last sync, **Sync now**, **Open in Overleaf** and **Unlink**. See [Overleaf](overleaf.md) for linking a folder and what a sync does. ## Supported providers Install Git and configure authentication on the machine running your Scient server. For a remote environment, do this on the remote machine. After signing in, open **Settings → Source control** and choose **Rescan**. Scient works with the platforms your team already uses: - **GitHub** – Pull requests, repository creation, and clone integration - **GitLab** – Merge requests, repository publishing, and hosted clones - **Forgejo and Gitea** – Pull requests, publishing, and clones through `fj` or `tea` - **Bitbucket** – Pull request workflows (via API token authentication) - **Azure DevOps** – Pull request support for Microsoft-hosted repositories - **Cursor Origin** – Clones and publishing through the `origin` CLI Scient 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. **Sign in with GitHub** in the same place, through the Scient for GitHub app. GitHub shows a code to enter; no GitHub CLI or token is needed. The app reaches only the accounts and organizations it is installed on; **Install on an organization** adds one. 3. `GH_TOKEN` (`GH_ENTERPRISE_TOKEN` with `GH_HOST` for GitHub Enterprise Server) in the server's environment. 4. [GitHub CLI](https://cli.github.com/) 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. Older GitHub and Bitbucket settings migrate into the shared host configuration. Existing host and token choices, including explicitly cleared tokens, take precedence; missing legacy entries are adopted independently. Adopted credentials are copied to their new secret-store names before the old copies are retired. If copying or retirement fails, the original settings remain available for retry instead of dropping credential recovery state. Clearing a migrated token does not leave an adopted legacy copy behind. ## What you can do ### Start projects from anywhere **Clone repositories directly** - Open the Command Palette (`Cmd/Ctrl + K`) → **Add Project** - Choose a connected source-control provider, or paste any **Git URL** - Enter the repository path (`owner/repo`, `group/project`, `workspace/repository`, or `project/repository`) or a full Git URL, pick a destination, and start working **Publish local projects to the cloud** - Have a local Git repository without a remote? - Use the **Publish Repository** action to create a new hosted repository, add it as your origin remote, and push, in one flow - If the local repository has no commits yet, publishing creates the remote and wires it up but does not push. Make a commit, then push normally. ### Manage Code Reviews Without Context Switching **Create pull requests while you work** - Push a branch and create a pull request from the Git actions controls in the toolbar - Scient can suggest titles and descriptions based on your commits - With **Repository conventions** selected, generated source control text follows the project's `AGENTS.md` along with recent commit subjects. Claude writers also follow `CLAUDE.md` - Supports GitHub Pull Requests, GitLab Merge Requests, Bitbucket Pull Requests, and Azure DevOps Pull Requests **Stay on top of open reviews** - See if your current branch already has an open PR/MR - When an agent finishes a turn on your thread's branch, Scient checks for a newly opened PR/MR if background activity is enabled for that repository. Known reviews keep their normal refresh schedule. - Open several reviews from the **Pull requests** page as tabs in the right panel - Filter the Pull requests page by source-control provider when several hosts are connected - Your authored reviews stay at the top and use the selected sort within their group. By default, see passing and approved reviews first, passing reviews awaiting approval next, and conflicting reviews last. Smaller changes come first within each readiness group, and finished reviews follow open work when all states are visible. - Forgejo warning checks stay distinct from passed checks. A watcher does not report an all-required-checks-passed result while a required check has a warning. Older apps keep showing these checks as pending rather than incorrectly treating them as passed. - Filter by author or labels. GitHub, GitLab, Forgejo, and GitCafe search option values on the host; Azure DevOps and Bitbucket use only facets from pull requests already loaded. Searches return at most 100 matches; refine the query when Scient says more are available. A supported repository search failure keeps options from successful repositories visible and marks the results incomplete; if failures leave no options, Scient reports an error rather than a complete empty result. Up to ten label filters can be combined. Existing groups keep their OR alternatives when edited; remove every alternative from a group to free its filter slot. - The list sends each filter to a host when that host supports it; filters without host support narrow the pull requests already loaded. Author ranking by merges still uses loaded results. See label and change-size context on each row, and sort the displayed results by readiness, update time, creation time, or change size. Your filters, search, scope, and sort are restored when you return. - Merge now, or on GitHub, GitLab, and Azure DevOps, leave an auto-merge instruction with a chosen strategy while checks are outstanding; see the completed state in the same control after the pull request merges - On GitHub, approve fork workflows that are waiting to run and open a revert pull request for a merged change - Timeline line counts stay hidden on merge commits, where GitHub's totals include upstream changes brought in from the base branch - While working in a thread, open linked reviews in the same compact right-panel tabs without leaving the conversation - Show a file tree next to a review's **Code** tab, or a thread's **Diff** panel, to browse the changed files as folders and jump straight to any of them. The toolbar toggle remembers your choice. - Enable **Settings → Diffs & pull requests → Proactive panels** to open a newly linked review automatically and switch to the completed turn's diff when agent work finishes - Open the review directly in your browser with one click - If Scient cannot load a GitHub pull request, including when GitHub rate-limits requests, use **Open on GitHub** in the error view - Command-click (Control-click on Windows and Linux) a pull request number in the sidebar to open it in your browser instead of in Scient - Check out a teammate's branch to review code locally **Fix what you wrote, in place** - Comment while closing an open pull request or reopening a closed one when the host offers that action - Rewrite a pull request's title and description from the review itself, in Markdown, with a preview before you save - Where you can edit a description, tick its checkboxes from the Summary tab (the Overview tab on mobile) - Rewrite your own comments the same way, wherever they are shown - Works on GitHub, GitLab, and Bitbucket. Azure DevOps takes a new title and description; its comments stay read-only here, as they already were - On GitHub, put a label on a pull request or take one off from the **Labels** row of the review. Changing labels needs triage access or better on the repository ### Know Your Setup at a Glance The **Source Control settings** page shows you exactly what's connected: - ✅ Which providers are authenticated and ready - ⚠️ What's missing and how to fix it - 👤 Which account is signed in (when available) Run a quick **Rescan** after setting up a new machine or changing credentials. ## Getting Started ### For GitHub (Recommended for most users) 1. Install the GitHub CLI (version 2.81.0 or newer) in the environment where the project runs: ```bash brew install gh ``` 2. Sign in: ```bash gh auth login ``` 3. Open **Settings → Source Control** in Scient and verify GitHub shows as authenticated You can now clone, publish, and create pull requests. For GitHub Enterprise, sign in with `gh auth login --hostname YOUR_HOST`. Scient treats a custom server name as GitHub once it has a credential for that host. ### For GitLab 1. Install the GitLab CLI: ```bash brew install glab ``` 2. Authenticate: ```bash glab auth login ``` 3. Check **Settings → Source Control** to confirm the connection ### For Forgejo and Gitea Install [Forgejo CLI (`fj`)](https://codeberg.org/forgejo-contrib/forgejo-cli) or [Gitea CLI (`tea`)](https://gitea.com/gitea/tea) 0.16 or later in the environment where the project runs. Sign in with `fj --host https://your-server auth add-token` or `tea login add`, then rescan **Settings → Source Control**. Scient prefers a matching `fj` login and falls back to `tea` when needed. Use a full repository URL when several servers are configured. Servers hosted below a URL subpath use `tea`, because `fj` 0.6 does not preserve that subpath while checking accounts. Git clone and push still require Git credentials or an SSH key. ### For Bitbucket Bitbucket uses tokens instead of a CLI tool. Save them in **Settings → Source Control**, or set them as environment variables on the machine running the Scient environment. The `T3CODE_` variable prefix below is a retained upstream compatibility identifier. It does not send credentials to T3, but changing the prefix would break existing configurations and requires a separate migration. 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, Scient falls back to these environment variables on the machine running the environment. Restart the Scient environment after changing them: ```bash export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token" # or export T3CODE_BITBUCKET_EMAIL="you@example.com" export T3CODE_BITBUCKET_API_TOKEN="your-token" ``` If both are set, the access token wins. Restart the Scient environment and verify the connection in **Source Control settings**. ### For Azure DevOps 1. Install Azure CLI: ```bash brew install azure-cli ``` 2. Add the DevOps extension: ```bash az extension add --name azure-devops ``` 3. Sign in: ```bash az login ``` ### GitCafe Install the GitCafe CLI and sign in: ```bash 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. ### Cursor Origin Install the [Origin CLI](https://cursor.com/docs/origin/cli) and sign in. Signing in also sets up Git credentials for `origin.cursor.com`: ```bash curl -fsSL https://downloads.cursor.com/origin/install.sh | sh origin auth login ``` If cloning or pushing asks for a username, run `origin auth setup-git` to point Git at the CLI's credentials again. Origin repositories use HTTPS and are published privately. Repositories mirrored from GitHub keep their pull requests on GitHub; open those from the GitHub remote. ## Requirements and troubleshooting 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, Scient clones over HTTPS with Git's credentials for that host instead, and the project's remote uses the HTTPS URL. To lay clones out like [ghq](https://github.com/x-motemen/ghq), turn on **Clone into host folders** under **Settings → Threads** (or **Source control** on mobile). Clones then default to `//` under **Add project starts in**, so set that to `~/ghq` to share ghq's folders. You can still change the destination before cloning. **Git is required only for source-control operations** — Ordinary folders, chat, files, terminals, browser tools, compute, and agents continue to work without Git. Cloning, branches, worktrees, diffs, commits, pushes, and Git checkpoints require Git in the project environment. When Git is missing, the composer can ask the selected agent to install it without replacing your current draft. **Environment-side setup** — Authentication happens in the environment where the project runs, not necessarily on the device displaying Scient. An administrator may have already configured a shared environment. Use a thread's Git actions to commit, push, and create a pull request. Scient 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. **Common issues:** - **Provider shows "Not authenticated"** – Run the login command for that provider (e.g., `gh auth login`) in a terminal on the server, then rescan in Settings - **GitHub says it could not verify sign-in status** — Scient needs GitHub CLI 2.81.0 or newer to check sign-in status. Update `gh` (for example, `brew upgrade gh`), then rescan - **Bitbucket not connecting** – Double-check your environment variables are set in the correct shell profile and the server was restarted - **Can't push to a remote** – Verify your Git remote URL matches the provider you've authenticated with (SSH vs HTTPS remotes may need different credentials) 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=/`. Choose how commit messages and pull request titles and descriptions are written in **Settings → Source control → Commits & pull requests**. **Repository conventions** uses the project's instructions and recent commit subjects. **Custom instructions** applies your own instructions to commits and pull requests. **Need more help?** Check your provider's CLI documentation: - [GitHub CLI](https://cli.github.com/) - [GitLab CLI](https://gitlab.com/gitlab-org/cli) - [Forgejo CLI](https://codeberg.org/forgejo-contrib/forgejo-cli) - [Gitea CLI](https://gitea.com/gitea/tea) - [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/) 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. ## Trusted pull request sharing Pull request sharing is off by default. In **Settings → Environments → Pull request sharing** (**Pull request routing** under **Environments** on mobile), choose **Read PRs** or **Read and act** only for environments you trust to share their source control access. Enable both the original environment and the environment answering its requests on that client. When enabled, review details, linked status, and permitted review actions can use another connected environment signed in to the same account on the same host. Each participating environment needs a project on that host. A connected local environment is preferred for actions and can answer slow or failed reads. Browser and mobile clients need a paired environment to use its GitHub credentials. Credentials remain on their machines. **Read and act** may use broader permissions than the original environment, so enable it only for environments you control. 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 retried automatically on another environment. Changing a saved endpoint or removing an environment clears its routing permission. 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 Scient and github.com in either direction. Forgejo, GitLab, Bitbucket, Azure DevOps, and Cursor Origin expose no record Scient 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 Scient**. 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 the `link_pull_request` tool. Use **Link pull request to thread** in the command palette to keep a pull request 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, a single review's number, or the total count of multiple unrelated 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. Ask the agent to watch, monitor, or babysit a pull request and it calls `watch_pull_request`. While the thread is active, the server checks the pull request every two minutes and wakes the agent when a check fails or waits for a maintainer's approval, the required checks pass, someone else comments or reviews, or the branch starts to conflict. Threads in a project that watch the same pull request share one check. On GitHub, a check first asks whether anything changed and reads the pull request only when it did, which keeps watching inside GitHub's rate limit. A terminal Forgejo warning does not satisfy a required-check pass. Comments from your own account do not wake it. Watching ends when the pull request 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 on the thread. A rate limit only pauses watching. Settling or archiving a thread also ends all its watches. 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. To start or stop it yourself, use the row menu in the **Linked pull requests** panel. In the thread details card, a watched pull request shows an eye; click it to stop watching. A watched thread counts as working between wakes, so it stays in the **Working** section and does not auto-settle. Agents stop watching when they hand the work back to you, and the thread then returns to your inbox. 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.