Setup
- Go to Organization → Integrations
- Find GitHub, click Install, and authorize your account
- If prompted, install the Replicas GitHub App on your repositories
- Add repositories to an environment with Add repository
@tryreplicas mentions on its issues and PRs. If your organization turns on Require Replicas account, each person must instead connect their own GitHub account under Personal → Connections.
Each repository can only be connected to one Replicas organization. If you need to transfer a repository to a different organization, remove it from the current organization first.
Default branch
Each repository has a configurable default branch that controls which branch new workspaces clone, which branch the Changes view diffs against, and which branch warm pools sync to. It defaults tomain. When you create a task from Home, you can choose a different starting branch for that workspace without changing the repository default.
To change it, open Organization → Integrations → GitHub, find the repository under Repositories (which also lists the environments using it), click the pencil icon next to the branch name, enter the new branch (e.g. staging, develop), and confirm. The setting is organization-scoped and applies to every workspace and warm pool that uses the repository.
Use it for repositories where your primary branch isn’t main, so workspaces start from the right branch and PR diffs are computed against the branch you actually merge into. A per-task branch choice changes only that workspace’s checkout and Changes baseline.
How It Works
Workspaces created from GitHub triggers use your organization’s default coding agent and model.Trigger from GitHub Issues
Add@tryreplicas to any comment on a GitHub issue to start a new task.
- Replicas creates a new workspace to work on the issue
- The agent provides an implementation plan before making changes
- When complete, the agent creates a PR and comments on the original issue with:
- A link to the PR
- A summary of the changes made
- When the issue is closed, the associated workspace is archived, keeping its conversation history; closing an issue never deletes the workspace
@tryreplicas wake or restore that workspace automatically.
If the agent cannot complete a turn started from an issue comment, Replicas posts the concrete error on the issue when available.
Trigger from Pull Requests
Add@tryreplicas to any pull request review (e.g requesting changes) or comment.
- If the pull request was made by a Replicas agent, it will see it, make changes, and respond directly to you.
- If the pull request was made by someone else, a new workspace and Replicas agent will be spun up.
Auto Respond To Review Bots And Users
You can configure an allowlist in Organization → Settings → Preferences → Review bots to automatically react to specific GitHub accounts (bots or users) without requiring@tryreplicas.
Search for reviewer bots like greptile-apps[bot], coderabbitai[bot], and copilot-swe-agent[bot] (the GitHub Copilot coding agent), or paste an exact login to add a non-bot user account, then add them to the allowlist.
Accounts not on the allowlist cannot trigger Replicas. When a known review bot (Greptile, CodeRabbit, Copilot, and others) comments on a Replicas PR without being on the list, Replicas replies once on the PR, and admins can turn the bot on from that PR’s workspace chat. If an unauthorized bot attempts to interact, it will receive a message directing org admins to add the login under Review bots.
After Replicas addresses actionable feedback from an enabled review bot, it always replies and tags the same bot account that sent the review. It does not reply to clean or acknowledgment-only bot messages.
On linked PRs, bot feedback—including Greptile reviews—runs in the same separate chat as CI fixes. Human comments continue in the main chat.
Silence Replicas On A Single PR
To stop Replicas from auto-responding on one specific pull request without changing any org-wide setting, add the labelreplicas-skip to the PR, or include a marker like [skip replicas] in the PR title or body. Replicas then stays quiet on that PR across every auto-respond path: review-bot and allowlisted-user comments, human PR reviews, and CI/CD failures.
An explicit @replicas mention still works and overrides the marker, so you can pull Replicas back in for a one-off reply. Accepted labels: replicas-skip, skip-replicas, replicas-ignore, no-replicas. Accepted title/body markers: [skip replicas], [replicas skip], [no replicas]. The same marker also mutes automations on the PR.
Human PR Review Auto-Response
By default, human PR reviews and inline review comments on Replicas-linked PRs do not trigger Replicas unless the reviewer mentions@tryreplicas, @replicas, or @replicas-connector.
Admins can turn on Organization → Settings → Preferences → CI failures and reviews → Respond to human PR reviews when they want Replicas to react to all human PR reviews on linked PRs. This does not affect auto responders or CI failure response.
Bot reviewers must still be enabled under Review bots; non-allowlisted bots do not auto-trigger from PR reviews.
CI failure response
When a CI/CD check fails on a pull request linked to a Replicas workspace, the agent is automatically notified and investigates the failure. It reads the failure logs, diagnoses the issue, pushes a fix, and comments on the PR. CI failures and review-bot feedback share a PR #… fixes chat forked from the main chat. Later feedback reuses that fork, keeping your main conversation uninterrupted. With Claude Code and Codex, the fork copies the main chat’s session, and re-copies it when the main chat has finished new turns, so it knows everything you’ve said there. Decisions you make about the PR (what to keep, avoid, or do a certain way) are also listed in its notes file. The fork won’t undo them just to satisfy a check or bot; it skips that fix and asks you to decide. Opening the workspace lands in the main chat. While only the fork is working, the sidebar shows a pull request icon instead of the loader, and the main chat shows a notice. The fork fixes the PR in its own git worktree, so it never touches the files the main chat is changing. With Claude Code, it tells the main chat what it’s fixing and when it pushes, and those messages show in both chats. Workspaces created from older sandbox images keep receiving this feedback in the main chat. CI failures wake a sleeping workspace automatically. Archived workspaces stay paused and must be restored before Replicas can respond to later failures. If the CI-triggered agent turn fails, Replicas posts the concrete error on the originating PR when available. This works with two sources of CI failures:- GitHub Actions workflows, triggered via
workflow_runevents when a workflow completes with a failure. - External CI checks, triggered via
check_runevents from any non-Actions provider that posts results through the GitHub Checks API (e.g. Mintlify, CircleCI, Buildkite).
- Respond to CI workflows: controls auto-response for GitHub Actions failures (enabled by default).
- Respond to CI checks: controls auto-response for external CI check failures (enabled by default).
CI providers that report status via the Statuses API or Deployments API (e.g. Vercel deployment status) are not yet covered by this feature.
PR Attribution
Pull requests created by Replicas agents use the Replicas bot by default. Organizations can require user attribution with Organization → Settings → Security → Require PR user attribution. When enabled, the code host tooling inside the workspace uses the triggering user’s personal code-host OAuth token, sogh pr create, GitLab merge request push options, pushes, and commit identity resolve to that user instead of the Replicas bot.
Turning on the organization policy automatically enables and locks Require code host connected and Require Replicas account because attribution cannot work without both.
Users can also require attribution for their own workspaces with Personal → Preferences → Require PR user attribution. This works even when the organization policy is off.
Commits made as you use your GitHub profile’s public email, or your GitHub noreply address when it has none. To use another email, pick one of your verified GitHub emails in Personal → Preferences → Commit email, and optionally set Commit name. This also applies to your co-author trailer. Services that match commit emails to accounts, like Vercel, need the email they know you by. Running workspaces switch on their next push or credential refresh.
Required attribution needs Replicas to resolve the triggering user and that user’s connected code-host account. Workspace creation and code-host token refresh fail closed until both are available.
Automation and API-key workspaces have no attached user and fall back to the Replicas bot for PR attribution.
Agents require the configured co-author trailers as one final block on every commit and include the same trailers at the end of pull request descriptions. Replicas checks each commit a command runs, whether its message comes from -m, a heredoc, -F <file>, --trailer, or --amend --no-edit; text that only mentions a commit, merge commits, and commits in a scratch repository the command creates are not checked. For repositories that squash merges, set the default squash commit message to Pull request title and description so GitHub preserves both user and Replicas attribution.
PR Merge Blocking
When the organization security policyblock_agent_pr_merges is enabled, agents are blocked from merging pull requests or merge requests. This prevents agents from bypassing human review by auto-merging their own work.
Blocked commands include gh pr merge, direct GitHub or GitLab API merge calls, and git push to the default branch, including after checking it out. When an agent attempts a blocked command, it receives a policy-blocked response naming this setting.
Agents can still update a feature branch from the default branch (git merge origin/main, git pull origin main, or git rebase origin/main) and push that feature branch.
This is controlled by Organization → Settings → Security → Block agent PR/MR merges. It is separate from Require PR user attribution, so organizations can enforce attribution without blocking merges, or block merges without changing attribution behavior.
Draft Pull Requests
Workspace agents can be instructed to open every new pull request as a draft. When enabled, the agent’s system prompt includes a clause telling it to usegh pr create --draft (or set "draft": true when hitting the GitHub REST API directly).
This feature is off by default and resolves in the standard order:
- User preference (
auto_draft_prs): Toggle Open new PRs as drafts in Personal → Preferences to draft PRs for your own workspaces. - Organization preference (
auto_draft_prs): Falls back to the org-level value when no user preference is set. - Default:
false(PRs are opened as normal pull requests).
Pull Request Discovery
On harnesses with post-tool hooks, Replicas links a pull request to its workspace as soon as the agent creates or pushes it, rather than waiting for the turn to end, so the workspace header, footer verification, and PR-linked triggers apply right away. Discovery also runs at the end of every turn, so pull requests opened outside a tool call or by harnesses without post-tool hooks are still picked up. Discovery only links PRs confirmed by the code host for branches used in the workspace. Viewing a PR, reading it through the API, or citing its URL in tool output or a report does not link it. Repositories the agent clones outside the workspace folder are included once it pushes from them, and appear in the workspace by their full path. External and nested Git worktrees are included. Claude publication events and successful Codex or OpenCode publishing-tool results also preserve PR links after a temporary worktree is removed. Commands with missing output or mixed results continue to use branch discovery. Pull requests in repositories that aren’t part of the workspace get no webhooks, so Replicas checks their status itself: every few minutes while they’re new, less often as they age. If Replicas can’t read one, for example because the GitHub App can’t access the repository or GitLab isn’t connected, the workspace’s pull request list says why its status won’t update. The same applies to GitLab merge requests.Replicas Footer
Every pull request opened from a workspace carries a footer crediting the person who started it and linking back to the workspace:app.replicas.dev/workspaces/.... Older replicas.dev/workspaces/... links still redirect; include both domains when counting Replicas-authored pull requests.
The same footer guarantee applies to GitLab merge requests, including eligible repositories cloned during a task.
Screenshots and GIFs
Agents add screenshots of visible changes to the description, and a looping GIF for motion or interactions, made withreplicas media gif. Both render inline on GitHub. GitHub can’t play videos, so a GIF links to the full recording when there is one.
In a workspace, gh pr create, gh pr edit, and gh pr comment (and the gh issue equivalents) accept --attach <image>. GitHub’s own attachment upload doesn’t accept the workspace’s GitHub App credential, so Replicas uploads the image as media and puts its link in the body. The link is unguessable but public: anyone who has it can view the image, including in private repositories. Images only; turn recordings into GIFs.
Graphite Pull Request Links
Enable Open pull requests in Graphite in Personal → Preferences to open GitHub pull requests in Graphite instead of GitHub. This turns Open on GitHub in the web and mobile apps into Open in Graphite, and Slack follow-ups and merged or closed PR notifications use Graphite links. In the app, pull request links still open the Replicas review first. Replicas continues to track the canonical GitHub URL, and GitLab merge request links are unchanged. Graphite merge queues close PRs on GitHub after landing them, and Replicas counts those PRs as merged. For other tools that close PRs after merging them, apply theexternally-merged label. Replicas counts closed PRs with this label as merged in Analytics. Adding the label after closure also corrects the tracked outcome.
Branch Rules
Merging from Replicas follows the base branch’s protection and rulesets. Merge is the main action unless GitHub is waiting on a review, when Approve leads instead. Hover a disabled merge button to see what’s missing, such as Requires 1 approving review or a failed required check. Replicas offers only the merge methods the repository and branch allow, starting with your default on GitHub. When the repository allows auto-merge, Enable auto-merge merges the pull request once its requirements pass. If GitHub lets you bypass the branch’s rules, a blocked pull request shows Bypass rules and merge. Replicas merges it right away with your connected GitHub account, skipping any merge queue. When Enable auto-merge is the main action, the bypass is in the ⋯ menu.GitHub Merge Queues
When a branch requires a merge queue, the merge button reads Add to merge queue. GitHub merges it with the queue’s merge method once the queue’s checks pass. Adding to a merge queue needs the Replicas GitHub App’s Merge queues permission. If GitHub asks your organization to approve an updated permission for the app, an organization owner approves it under Settings > GitHub Apps.Stacked Pull Requests
When GitHub pull requests in a workspace belong to a stack, the workspace header groups them in stack order and shows their shared base branch. Open each pull request from the stack view to review it in Replicas, and merge it on GitHub. Replicas disables the direct workspace merge action for stacked pull requests because the stack must be merged in order.Context
For issues, the context includes:- Issue number, title, and description
- Your comment body
- PR number and branch
- Your comment or review body
- Review state (approved, changes requested, etc.)
- File path and diff hunk (for line comments)
Intended Usage
Use GitHub Issues to:- Start new features or bug fixes directly from issue tracking
- Get implementation plans before code changes
- Track work from issue to PR automatically
- Request changes on PRs
- Comment on specific lines
- Ask for fixes or improvements
/plan to request a planning-only response with a plan link. See Plan Mode.